Skip to content
GitmoapAPIBeta
Organizeaccess
PATCH/access/grants/{grant_id}

Change a grant's role, expiry or reason.

update_access_grant
  • 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"}

  • Dry run
    Takes dry_run.

Send at least one of the three; an expiry must be in the future and at most a year away. Callers who can manage access at the grant's group or repository may call it, and must hold both the role it has and any role it is given. A grant whose access the caller cannot see is not found. A service account's own level is changed on the service account, not here. With dry_run=true the answer says what a change of role would do, and nothing changes.

Parameters

Path
  • grant_idGrantId (string · uuid)Grant ID
Query
  • dry_runbooleanoptionalSay what would change, and change nothing

Request body

application/json
  • expires_atstring · date-time or nulloptionalA new end date, or null for access that lasts until it is revoked.
  • reasonGrantReason (string) or nulloptionalA new reason, or null to clear it.
  • roleRoleRef or nulloptional
Request body exampleSynthesized example
{}

Responses

200The grant as it now stands, or a previewapplication/json
  • grantAccessGrant or nulloptionalThe grant as it stands after the change. For a preview, as it would stand.
    • 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.
    • 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.
    • last_exercised_atstring · date-time or nulloptionalWhen the grant last let somebody do something, to the day. Absent until it has.
    • 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.
200 exampleSynthesized example
{
"grant": {
"created_at": "2026-10-08T14:45:41Z",
"grant_id": "222a47f0-5d98-4984-b2f9-f5cb3ac43713",
"role": {
"name": "payments-api",
"rank": "guest",
"builtin": "guest",
"custom": "1b9eecaa-3cf9-412f-9817-0204079e5ad2"
},
"scope": {
"full_path": "acme/payments-api",
"id": "id-bd02",
"type": "group"
},
"subject": {
"principal": {
"id": "ee0daa69-067c-45c8-8f8a-647a82ca9220",
"kind": "user",
"username": "mara",
"avatar_url": "https://gitmoap.example/acme/a9f52ea6"
}
},
"updated_at": "2026-10-12T11:37:58Z",
"expires_at": "2026-10-11T10:36:28Z",
"granted_by": {
"email": "mara@acme.example",
"id": "id-f211",
"username": "lin",
"avatar_url": "https://gitmoap.example/acme/5a6f838e"
},
"last_exercised_at": "2026-10-13T08:37:20Z",
"reason": "reason-a222"
},
"preview": {
"changes": [
{
"gains": [],
"losses": [],
"principal": {
"id": "7463b45e-4aa2-408f-a9fd-4443c9097bc8",
"kind": "user",
"username": "tomas"
},
"scope": {
"full_path": "acme/payments-api",
"id": "id-fee9",
"type": "group"
}
},
{
"gains": [],
"losses": [],
"principal": {
"id": "371a68f0-5ed4-4761-9d61-050a4c99466d",
"kind": "user",
"username": "tomas"
},
"scope": {
"full_path": "acme/payments-api",
"id": "id-caf5",
"type": "group"
}
}
],
"summary": {
"people_gaining": 4,
"people_losing": 28,
"scopes_affected": 46
},
"truncated": false
}
}
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
{
"error": {
"code": "code-3bb3",
"message": "Stream pipeline status into the run header"
}
}
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
{
"error": {
"code": "code-330d",
"message": "Stream pipeline status into the run header"
}
}
403The caller cannot change this grantapplication/json
Error codes
  • ACCESS_ESCALATIONThe change would give someone more access than you hold yourself
  • 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
{
"error": {
"code": "code-b92b",
"message": "Draw the region map from operation density"
}
}
404Grant or role 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
{
"error": {
"code": "code-899a",
"message": "Inline scalar newtypes but keep their brand"
}
}
409This is a service account's own level — change it on the service accountapplication/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
  • USE_SERVICE_ACCOUNT_APIThis is a service account's access at its own home; change it on the service account
  • 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
{
"error": {
"code": "code-e92c",
"message": "Inline scalar newtypes but keep their brand"
}
}
422A service account cannot hold this role hereapplication/json
Error codes
  • 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
{
"error": {
"code": "code-b6e7",
"message": "Inline scalar newtypes but keep their brand"
}
}

CLI

gitmoap access update-access-grant

  • --grant-ididGrant ID
  • --dry-runflagoptionalSay what would change, and change nothing
  • --expires-atstringoptionalA new end date, or `null` for access that lasts until it is revoked.
  • --reasonstringoptional
  • --rolejsonoptional

Used in these guides