POST/groups/{group_id}/access/grants

Give one role to people, service accounts or teams on a group.

create_group_access_grants

access:manage
A token needs the access:manage scope: Give, change and revoke access to groups and repositoriesGranted by write_api.Every operation this scope unlocks
Audited · mutation
x-gitmoap-audit: {"kind":"audited","arg":"mutation"}
Quota · members per scope
x-gitmoap-quota: {"kind":"enforced","arg":"members_per_scope"}
Dry run
Takes dry_run.

Names up to 50 subjects, with an optional expiry (in the future, at most a year away) and reason. Callers who can manage access here may call it (Maintainers and above with the built-in roles), and nobody can give a role carrying a permission or rank they do not hold themselves. A subject that already holds the same role is reported as unchanged; one holding a different role is refused. A service account can be given access only at its own group or repository or beneath it, and never as Owner. With dry_run=true the answer says who would gain what, and nothing changes.

Parameters

Path

group_idGroupId (string · uuid)Group ID

Query

dry_runbooleanoptionalSay who would gain what, and change nothing

Request body

application/json

roleRoleRef
subjectsarray of SubjectRefWho receives the role — at most 50 subjects in one request.
expires_atstring · date-time or nulloptionalWhen the access ends. Omit it for access that lasts until it is revoked.
reasonGrantReason (string) or nulloptionalWhy the access is given, shown beside the grant and kept in the audit log.

Request body exampleSynthesized example

Responses

200A preview: who would gain what. Nothing was changedapplication/json

grantsarray of AccessGrantThe grants made. Empty for a preview.
- The AccessGrant schema
- created_atstring · date-time
- grant_idGrantId (string · uuid)
- roleRoleView
  - 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.
- scopeAccessScopeWhere the grant was made.
  - The AccessScope schema
  - full_pathstring
  - idstring
  - typeScopeTypegrouprepository
- subjectGrantSubject
- updated_atstring · date-time
- expires_atstring · date-time or nulloptional
- granted_byActorSummary or nulloptionalWho made the grant. Absent for access the platform created — the creator of a group or repository, or a copied membership.
  - The ActorSummary schema
  - emailstring
  - idstring
  - usernamestring
  - avatar_urlstring or nulloptional
- last_exercised_atstring · date-time or nulloptionalWhen the grant last let somebody do something, to the day. Absent until it has.
- reasonstring or nulloptional
unchangedarray of UnchangedGrantSubjects that already held the role here and were left as they were.
- The UnchangedGrant schema
- grant_idGrantId (string · uuid)
- reasonUnchangedReasonalready_granted_same_roleWhy a subject named in a create request was left as it was.
- subjectSubjectRef
previewAccessPreview or nulloptionalPresent only for a preview: who would gain what. Nothing was written.
- 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.

200 exampleSynthesized example

201Access givenapplication/json

grantsarray of AccessGrantThe grants made. Empty for a preview.
- The AccessGrant schema
- created_atstring · date-time
- grant_idGrantId (string · uuid)
- roleRoleView
  - 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.
- scopeAccessScopeWhere the grant was made.
  - The AccessScope schema
  - full_pathstring
  - idstring
  - typeScopeTypegrouprepository
- subjectGrantSubject
- updated_atstring · date-time
- expires_atstring · date-time or nulloptional
- granted_byActorSummary or nulloptionalWho made the grant. Absent for access the platform created — the creator of a group or repository, or a copied membership.
  - The ActorSummary schema
  - emailstring
  - idstring
  - usernamestring
  - avatar_urlstring or nulloptional
- last_exercised_atstring · date-time or nulloptionalWhen the grant last let somebody do something, to the day. Absent until it has.
- reasonstring or nulloptional
unchangedarray of UnchangedGrantSubjects that already held the role here and were left as they were.
- The UnchangedGrant schema
- grant_idGrantId (string · uuid)
- reasonUnchangedReasonalready_granted_same_roleWhy a subject named in a create request was left as it was.
- subjectSubjectRef
previewAccessPreview or nulloptionalPresent only for a preview: who would gain what. Nothing was written.
- 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.

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

403The caller cannot give this role 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

409A subject already holds a different role 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

422A service account cannot hold this role hereapplication/json

Error codes

UNPROCESSABLE_ENTITYThe request is well-formed but asks for something the resource's rules do not allow; reason says which

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.

422 exampleSynthesized example

429Access limit 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-grants

--group-ididGroup ID (id or group path)
--dry-runflagoptionalSay who would gain what, and change nothing
--expires-atstringoptionalWhen the access ends. Omit it for access that lasts until it is revoked.
--reasonstringoptional
--rolejson
--subjectsjsonWho receives the role — at most 50 subjects in one request.

Used in these guides

Access

Request

curl -X POST "https://api.gitmoap.com/groups//access/grants" \
  -H "Authorization: Bearer $GITMOAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role": {
      "builtin": "guest"
    },
    "subjects": [
      {
        "principal": "a2aa70d9-850c-4842-813a-210a9d7bdc84"
      },
      {
        "principal": "412de273-4d29-4471-b6b6-e445ee2db491"
      }
    ]
  }'

gitmoap access create-group-access-grants \
  --group-id  \
  --role @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/grants", {
  params: {
    path: { group_id: "" },
  },
  body: {
    role: {
      builtin: "guest"
    },
    subjects: [
      {
        principal: "a2aa70d9-850c-4842-813a-210a9d7bdc84"
      },
      {
        principal: "412de273-4d29-4471-b6b6-e445ee2db491"
      }
    ]
  },
});

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

{
  "role": {
    "builtin": "guest"
  },
  "subjects": [
    {
      "principal": "a2aa70d9-850c-4842-813a-210a9d7bdc84"
    },
    {
      "principal": "412de273-4d29-4471-b6b6-e445ee2db491"
    }
  ]
}

The body's other fields

⌘↵

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