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

Create a custom Role

Requires ac:create; granting organization:delete also requires organization:delete. Built-in names are reserved, names are unique within the organization (409), and every resource a Grant selects must belong to the organization (400).

POST/organizations/{organizationId}/roles
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
Request body
requiredapplication/json
namestringrequired

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

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
Responses
201

The created 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 POST 'https://auth.kapten.io/organizations/497f6eca-6276-4993-bfeb-53cbbbba6f08/roles' \
  -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?