Roles
Returns the built-in roles in catalog order, then the organization's custom roles by name.
user_jwt read:organizationAuthorizationBearer <token>Bearer access token for a signed-in user.
Scope: read:organization
org_id*stringThe organization ID
uuidThe organization roles
application/json- response
max_custom_roles*integerThe most custom roles the organization can define.
int64roles*array<>The built-in roles, then the organization's custom roles.
curl -X GET 'https://example.com/orgs/497f6eca-6276-4993-bfeb-53cbbbba6f08/roles'{ "max_custom_roles": 0, "roles": [ { "created_at": "2019-08-24T14:15:22Z", "description": "string", "id": "string", "kind": "built_in", "name": "string", "organization_permissions": [ "string" ], "permissions": [ "string" ], "project_permissions": [ "string" ], "updated_at": "2019-08-24T14:15:22Z" } ]}Defines a custom role from the permission vocabulary. The role can grant only permissions the current member holds.
user_jwt write:rolesAuthorizationBearer <token>Bearer access token for a signed-in user.
Scope: write:roles
org_id*stringThe organization ID
uuidapplication/json- body
description?stringThe role's purpose.
length <= 256name*stringThe role name, unique in the organization ignoring case. Leading and trailing whitespace is removed and internal whitespace runs collapse to one space; the result must be 1 to 64 characters.
1 <= lengthorganization_permissions*array<string>The organization permissions the role grants.
project_permissions*array<string>The project permissions the role grants.
The created organization role
application/json- response
created_at?|When the role was created, or null for a built-in role.
date-timedescription*stringThe role's purpose.
id*stringThe role ID: a built-in role's identifier, or a custom role's UUID.
kind*OrganizationRoleKindWhether the role is built in or defined by the organization.
"built_in""custom"name*stringThe display name.
organization_permissions*array<string>The organization permissions the role grants.
permissions*array<string>Every permission the role grants: the project permissions, then the organization permissions.
project_permissions*array<string>The project permissions the role grants.
updated_at?|When the role was last changed, or null for a built-in role.
date-timecurl -X POST 'https://example.com/orgs/497f6eca-6276-4993-bfeb-53cbbbba6f08/roles' \ -H 'Content-Type: application/json' \ -d '{ "name": "string", "organization_permissions": [ "string" ], "project_permissions": [ "string" ]}'{ "created_at": "2019-08-24T14:15:22Z", "description": "string", "id": "string", "kind": "built_in", "name": "string", "organization_permissions": [ "string" ], "permissions": [ "string" ], "project_permissions": [ "string" ], "updated_at": "2019-08-24T14:15:22Z"}user_jwt read:organizationAuthorizationBearer <token>Bearer access token for a signed-in user.
Scope: read:organization
org_id*stringThe organization ID
uuidrole_id*stringThe role ID
The organization role
application/json- response
created_at?|When the role was created, or null for a built-in role.
date-timedescription*stringThe role's purpose.
id*stringThe role ID: a built-in role's identifier, or a custom role's UUID.
kind*OrganizationRoleKindWhether the role is built in or defined by the organization.
"built_in""custom"name*stringThe display name.
organization_permissions*array<string>The organization permissions the role grants.
permissions*array<string>Every permission the role grants: the project permissions, then the organization permissions.
project_permissions*array<string>The project permissions the role grants.
updated_at?|When the role was last changed, or null for a built-in role.
date-timecurl -X GET 'https://example.com/orgs/497f6eca-6276-4993-bfeb-53cbbbba6f08/roles/string'{ "created_at": "2019-08-24T14:15:22Z", "description": "string", "id": "string", "kind": "built_in", "name": "string", "organization_permissions": [ "string" ], "permissions": [ "string" ], "project_permissions": [ "string" ], "updated_at": "2019-08-24T14:15:22Z"}Updates a custom role; a permission array in the request replaces the stored array. Narrowing a role revokes its holders' API keys that exceed their new permissions. An update that only removes permissions does not require the custom roles entitlement.
user_jwt write:rolesAuthorizationBearer <token>Bearer access token for a signed-in user.
Scope: write:roles
org_id*stringThe organization ID
uuidrole_id*stringThe role ID
application/json- body
description?stringThe new role purpose.
length <= 256name?stringThe new role name. Whitespace is normalized as on create; the result must be 1 to 64 characters.
1 <= lengthorganization_permissions?array<string>The complete new set of organization permissions.
project_permissions?array<string>The complete new set of project permissions.
The organization role
application/json- response
A role update's result: the role and the keys the update revoked.
revoked_api_keys*integerThe number of API keys the update revoked.
int640 <= valuerole*The updated role.
curl -X PATCH 'https://example.com/orgs/497f6eca-6276-4993-bfeb-53cbbbba6f08/roles/string' \ -H 'Content-Type: application/json' \ -d '{}'{ "revoked_api_keys": 0, "role": { "created_at": "2019-08-24T14:15:22Z", "description": "string", "id": "string", "kind": "built_in", "name": "string", "organization_permissions": [ "string" ], "permissions": [ "string" ], "project_permissions": [ "string" ], "updated_at": "2019-08-24T14:15:22Z" }}Deletes a custom role that no member, service account, or pending invitation holds.
user_jwt delete:rolesAuthorizationBearer <token>Bearer access token for a signed-in user.
Scope: delete:roles
org_id*stringThe organization ID
uuidrole_id*stringThe role ID
Role deleted
curl -X DELETE 'https://example.com/orgs/497f6eca-6276-4993-bfeb-53cbbbba6f08/roles/string'Reports what the same update would change, without applying it. A preview that only removes permissions does not require the custom roles entitlement.
user_jwt write:rolesAuthorizationBearer <token>Bearer access token for a signed-in user.
Scope: write:roles
org_id*stringThe organization ID
uuidrole_id*stringThe role ID
application/json- body
description?stringThe new role purpose.
length <= 256name?stringThe new role name. Whitespace is normalized as on create; the result must be 1 to 64 characters.
1 <= lengthorganization_permissions?array<string>The complete new set of organization permissions.
project_permissions?array<string>The complete new set of project permissions.
The role change impact
application/json- response
affected_members*integerThe number of members who hold the role.
int640 <= valueaffected_service_accounts*integerThe number of active service accounts that hold the role.
int640 <= valuepending_invitations*integerThe number of pending invitations that grant the role.
int640 <= valuerevoked_api_keys*integerThe number of API keys the update would revoke.
int640 <= valuecurl -X POST 'https://example.com/orgs/497f6eca-6276-4993-bfeb-53cbbbba6f08/roles/string/update-preview' \ -H 'Content-Type: application/json' \ -d '{}'{ "affected_members": 0, "affected_service_accounts": 0, "pending_invitations": 0, "revoked_api_keys": 0}AuthorizationBearer <token>Bearer access token for a signed-in user.
scope?stringRestrict the catalog to one permission scope.
"project""organization"The permission catalog
application/json- response
permissions*array<>The available permissions.
curl -X GET 'https://example.com/permissions'{ "permissions": [ { "category": "string", "id": "string", "name": "string" } ]}AuthorizationBearer <token>Bearer access token for a signed-in user.
The role catalog
application/json- response
roles*array<>The available roles.
curl -X GET 'https://example.com/roles'{ "roles": [ { "description": "string", "id": "string", "name": "string", "permissions": [ "string" ] } ]}