Skip to content
Kapten
Esc
↑↓navigate↵open⌘Jpreview

Rename a custom Role or replace its Grants

Requires ac:update; replacing the Grants of a Role that grants, or would grant, organization:delete also requires organization:delete. Grants, when present, replace every Grant of the Role. Built-in Roles cannot change (409).

PATCH/organizations/{organizationId}/roles/{roleId}
Authorization
AuthorizationBearer token (JWT) · headerrequired

An access token issued by this service (RFC 9068), in the Authorization header as Bearer <token>.

Path parameters
organizationIdstring<uuid>required
roleIdstring<uuid>required
Request body
requiredapplication/json
namestring

Trimmed and lower-cased; 1 to 64 characters, not a built-in name.

grantsgrant_document

A Role's Grants as scoped statements. Statements add together. Responses are canonical, one statement per scope instance.

Show properties
versionintegerrequired
Allowed:1
statementsgrant_statement[]required
max items 500
Show properties
Array of grant_statement
scopegrant_scoperequired

The organization, every instance of a project, cluster or integration type (all), or selected instances (ids).

Show properties
typescope_typerequired
Allowed:organizationprojectenvironmentclusterintegration
idsstring<uuid>[]
min items 1 · max items 100
allboolean
permissionsstring[]required

Permissions compatible with the scope, as resource:action.

min items 1 · max items 50
Responses
200

The updated Role.

idstring<uuid>required
namestringrequired
builtinbooleanrequired

Built-in Roles (owner, admin, member) cannot be renamed, edited or deleted.

grantsgrant_documentrequired

A Role's Grants as scoped statements. Statements add together. Responses are canonical, one statement per scope instance.

Show properties
versionintegerrequired
Allowed:1
statementsgrant_statement[]required
max items 500
Show properties
Array of grant_statement
scopegrant_scoperequired

The organization, every instance of a project, cluster or integration type (all), or selected instances (ids).

Show properties
typescope_typerequired
Allowed:organizationprojectenvironmentclusterintegration
idsstring<uuid>[]
min items 1 · max items 100
allboolean
permissionsstring[]required

Permissions compatible with the scope, as resource:action.

min items 1 · max items 50
created_atstring<date-time>required
default

The request failed.

errorstringrequired

Stable machine-readable code.

Allowed:invalid_requestunauthorizedforbiddennot_foundconflictgoneunavailableinternal
messagestringrequired

Human-readable explanation.

Request
curl -X PATCH 'https://auth.kapten.io/organizations/497f6eca-6276-4993-bfeb-53cbbbba6f08/roles/497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "grants": {
    "version": 1,
    "statements": [
      {
        "scope": {
          "type": "organization",
          "ids": [
            "497f6eca-6276-4993-bfeb-53cbbbba6f08"
          ],
          "all": true
        },
        "permissions": [
          "string"
        ]
      }
    ]
  }
}'
Response
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "builtin": true,
  "grants": {
    "version": 1,
    "statements": [
      {
        "scope": {
          "type": "organization",
          "ids": [
            "497f6eca-6276-4993-bfeb-53cbbbba6f08"
          ],
          "all": true
        },
        "permissions": [
          "string"
        ]
      }
    ]
  },
  "created_at": "2019-08-24T14:15:22Z"
}

Was this page helpful?