POST/groups/{group_id}/access/limits

Cap someone on a group and everything beneath it, whatever they are granted.

create_group_access_limit

access:administer
A token needs the access:administer scope: Limit access, and stop a group or repository inheriting itEvery operation this scope unlocks
Audited · mutation
x-gitmoap-audit: {"kind":"audited","arg":"mutation"}
Quota · limits per scope
x-gitmoap-quota: {"kind":"enforced","arg":"limits_per_scope"}
Dry run
Takes dry_run.

The subject is a person, a team, or a whole class (everyone, service accounts, agents); the ceiling is a built-in role, a custom role, or no access at all. A no-access limit cannot hide a public or internal group, and the answer warns when that is the case. Only the group's owners may call it. The answer says who the limit narrows; with dry_run=true nothing changes.

Parameters

Path

group_idGroupId (string · uuid)Group ID

Query

dry_runbooleanoptionalSay who would be narrowed, and change nothing

Request body

application/json

ceilingCeilingRef
subjectLimitSubjectRef
reasonGrantReason (string) or nulloptionalWhy the limit exists — shown beside it, and in access reviews.

Request body exampleSynthesized example

Responses

200A preview: who the limit would narrow. Nothing was changedapplication/json

limitAccessLimit
- The AccessLimit schema
- atAccessScopeWhere the limit is set. It caps its subject there and everywhere beneath, including beneath a group or repository that does not inherit access.
  - The AccessScope schema
  - full_pathstring
  - idstring
  - typeScopeTypegrouprepository
- created_atstring · date-time
- limit_idLimitId (string · uuid)
- subjectLimitSubjectEntry
- ceilingRoleView or nulloptionalThe most the subject may hold. Absent when the limit allows nothing at all.
  - The RoleView schema
  - namestringThe role's display name: a built-in name such as Developer, or the custom role's name.
  - rankAccessLevelguestreporterdevelopermaintainerownerThe built-in rank the role counts as wherever a rank is compared, such as a protected branch's minimum.
  - builtinAccessLevelguestreporterdevelopermaintainerowneror nulloptionalSet when the role is built in.
  - customRoleId (string · uuid) or nulloptionalSet when the role is one the organization defined.
- created_byActorSummary or nulloptional
  - The ActorSummary schema
  - emailstring
  - idstring
  - usernamestring
  - avatar_urlstring or nulloptional
- reasonstring or nulloptional
previewAccessPreview or nulloptional
- The AccessPreview schema
- changesarray of AccessDeltaEach person whose access would change at the group or repository the change is made on.
  - The AccessDelta schema
  - gainsarray of stringPermissions they would hold that they do not hold now, by key.
  - lossesarray of stringPermissions they hold now that they would no longer hold, by key.
  - principalPrincipalSummary
  - scopeAccessScope
  - rank_afterAccessLevelguestreporterdevelopermaintainerowneror nulloptional
  - rank_beforeAccessLevelguestreporterdevelopermaintainerowneror nulloptional
- summaryAccessPreviewSummary
  - The AccessPreviewSummary schema
  - people_gaininginteger · int320–∞
  - people_losinginteger · int320–∞
  - scopes_affectedinteger · int64The group or repository the change is made on, plus every one beneath it that inherits access and so changes with it.
- truncatedbooleanWhether changes stops short of everyone affected. The summary still counts them all.
warningsarray of LimitWarning: one of limit_cannot_hide_publicoptional

200 exampleSynthesized example

201The limit, and who it narrowedapplication/json

limitAccessLimit
- The AccessLimit schema
- atAccessScopeWhere the limit is set. It caps its subject there and everywhere beneath, including beneath a group or repository that does not inherit access.
  - The AccessScope schema
  - full_pathstring
  - idstring
  - typeScopeTypegrouprepository
- created_atstring · date-time
- limit_idLimitId (string · uuid)
- subjectLimitSubjectEntry
- ceilingRoleView or nulloptionalThe most the subject may hold. Absent when the limit allows nothing at all.
  - The RoleView schema
  - namestringThe role's display name: a built-in name such as Developer, or the custom role's name.
  - rankAccessLevelguestreporterdevelopermaintainerownerThe built-in rank the role counts as wherever a rank is compared, such as a protected branch's minimum.
  - builtinAccessLevelguestreporterdevelopermaintainerowneror nulloptionalSet when the role is built in.
  - customRoleId (string · uuid) or nulloptionalSet when the role is one the organization defined.
- created_byActorSummary or nulloptional
  - The ActorSummary schema
  - emailstring
  - idstring
  - usernamestring
  - avatar_urlstring or nulloptional
- reasonstring or nulloptional
previewAccessPreview or nulloptional
- The AccessPreview schema
- changesarray of AccessDeltaEach person whose access would change at the group or repository the change is made on.
  - The AccessDelta schema
  - gainsarray of stringPermissions they would hold that they do not hold now, by key.
  - lossesarray of stringPermissions they hold now that they would no longer hold, by key.
  - principalPrincipalSummary
  - scopeAccessScope
  - rank_afterAccessLevelguestreporterdevelopermaintainerowneror nulloptional
  - rank_beforeAccessLevelguestreporterdevelopermaintainerowneror nulloptional
- summaryAccessPreviewSummary
  - The AccessPreviewSummary schema
  - people_gaininginteger · int320–∞
  - people_losinginteger · int320–∞
  - scopes_affectedinteger · int64The group or repository the change is made on, plus every one beneath it that inherits access and so changes with it.
- truncatedbooleanWhether changes stops short of everyone affected. The summary still counts them all.
warningsarray of LimitWarning: one of limit_cannot_hide_publicoptional

201 exampleSynthesized example

400Invalid requestapplication/json

Error codes

BAD_REQUESTThe request is malformed: a parameter or a body field is not a well-formed value of its type

errorErrorBody
- The ErrorBody schema
- codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
- messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
- fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
- reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
- required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
- violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.

400 exampleSynthesized example

401Authentication requiredapplication/json

Error codes

UNAUTHORIZEDNo credential was sent, or the one sent is invalid, expired or revoked

errorErrorBody
- The ErrorBody schema
- codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
- messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
- fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
- reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
- required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
- violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.

401 exampleSynthesized example

403Only the owners of the group can limit access hereapplication/json

Error codes

FORBIDDENYou are signed in but may not do this here; reason names the permission or the rule that refused it
INSUFFICIENT_SCOPEThe access token lacks the scope this operation needs; required_scope names it
PERMISSION_REQUIREDYou need a permission you do not hold here; the message names it

errorErrorBody
- The ErrorBody schema
- codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
- messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
- fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
- reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
- required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
- violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.

403 exampleSynthesized example

404Group, role or subject not foundapplication/json

Error codes

NOT_FOUNDThe resource does not exist — or exists and you cannot see it: a private resource you have no access to answers exactly as an absent one does

errorErrorBody
- The ErrorBody schema
- codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
- messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
- fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
- reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
- required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
- violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.

404 exampleSynthesized example

409The subject is already limited hereapplication/json

Error codes

CONFLICTThe request conflicts with the resource's current state; reason says how
LEGAL_ACCEPTANCE_REQUIREDAccept the current Terms of Service before changing anything; reading stays open

errorErrorBody
- The ErrorBody schema
- codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
- messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
- fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
- reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
- required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
- violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.

409 exampleSynthesized example

429Limit cap reached for this groupapplication/json

Error codes

TOO_MANY_REQUESTSRetryableA quota, a rate limit or a transfer budget is spent. When the response carries Retry-After, retry after that many seconds

errorErrorBody
- The ErrorBody schema
- codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
- messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
- fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
- reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
- required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
- violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.

429 exampleSynthesized example

CLI

gitmoap access create-group-access-limit

--group-ididGroup ID (id or group path)
--dry-runflagoptionalSay who would be narrowed, and change nothing
--ceilingjson
--reasonstringoptional
--subjectjson

Used in these guides

Access

Request

curl -X POST "https://api.gitmoap.com/groups//access/limits" \
  -H "Authorization: Bearer $GITMOAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ceiling": {
      "builtin": "guest"
    },
    "subject": {
      "principal": "61971e7e-7e3c-4c6d-ad90-61f5a42a9166"
    }
  }'

gitmoap access create-group-access-limit \
  --group-id  \
  --ceiling @body.json

import { createApiClient } from "@gitmoap/backend-types";

const client = createApiClient({
  baseUrl: "https://api.gitmoap.com",
  headers: { Authorization: `Bearer ${process.env.GITMOAP_TOKEN}` },
});

const { data, error } = await client.POST("/groups/{group_id}/access/limits", {
  params: {
    path: { group_id: "" },
  },
  body: {
    ceiling: {
      builtin: "guest"
    },
    subject: {
      principal: "61971e7e-7e3c-4c6d-ad90-61f5a42a9166"
    }
  },
});

POST /groups//access/limits HTTP/1.1
Host: api.gitmoap.com
Authorization: Bearer $GITMOAP_TOKEN
Content-Type: application/json

{
  "ceiling": {
    "builtin": "guest"
  },
  "subject": {
    "principal": "61971e7e-7e3c-4c6d-ad90-61f5a42a9166"
  }
}

The body's other fields

⌘↵

Send to see the sandbox's answer. Nothing leaves your browser.