Access
Principals, groups, roles, and role bindings.
Operations
Each operation lists its specific responses. See Common error responses for errors shared by every operation on this page.
List principals
GET /api/v1/principals
Operation ID: listPrincipals
Effect: read
Confirmation: never
Required privilege: MANAGE_GRANTS
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
email |
query | No | string | |
q |
query | No | string | |
limit |
query | No | integer | |
pageToken |
query | No | string |
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
Create a local principal
POST /api/v1/principals
Operation ID: createPrincipal
Effect: write
Confirmation: conditional
Required privilege: MANAGE_GRANTS
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
Idempotency-Key |
header | Yes | string |
Request body
Content types: application/json.
Responses
| Status | Description |
|---|---|
201 |
The request has succeeded and a new resource has been created as a result. |
Delete a principal
DELETE /api/v1/principals/{principal}
Operation ID: deletePrincipal
Effect: destructive
Confirmation: required
Required privilege: MANAGE_GRANTS
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
principal |
path | Yes | string |
Responses
| Status | Description |
|---|---|
204 |
There is no content to send for this request, but the headers may be useful. |
Get a principal
GET /api/v1/principals/{principal}
Operation ID: getPrincipal
Effect: read
Confirmation: never
Required privilege: MANAGE_GRANTS
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
principal |
path | Yes | string |
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
Update a principal
PATCH /api/v1/principals/{principal}
Operation ID: updatePrincipal
Effect: write
Confirmation: conditional
Required privilege: MANAGE_GRANTS
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
principal |
path | Yes | string | |
If-Match |
header | Yes | string |
Request body
Content types: application/json.
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
Reset a local principal password
POST /api/v1/principals/{principal}/password-reset
Operation ID: resetPrincipalPassword
Effect: write
Confirmation: conditional
Required privilege: MANAGE_GRANTS
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
principal |
path | Yes | string | |
Idempotency-Key |
header | Yes | string |
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
List service principals
GET /api/v1/service-principals
Operation ID: listServicePrincipals
Effect: read
Confirmation: never
Required privilege: MANAGE_PLATFORM
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
limit |
query | No | integer | |
pageToken |
query | No | string |
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
Create a service principal
POST /api/v1/service-principals
Operation ID: createServicePrincipal
Effect: write
Confirmation: conditional
Required privilege: MANAGE_PLATFORM
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
Idempotency-Key |
header | Yes | string |
Request body
Content types: application/json.
Responses
| Status | Description |
|---|---|
201 |
The request has succeeded and a new resource has been created as a result. |
Delete a service principal
DELETE /api/v1/service-principals/{servicePrincipal}
Operation ID: deleteServicePrincipal
Effect: destructive
Confirmation: required
Required privilege: MANAGE_PLATFORM
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
servicePrincipal |
path | Yes | string |
Responses
| Status | Description |
|---|---|
204 |
There is no content to send for this request, but the headers may be useful. |
Get a service principal
GET /api/v1/service-principals/{servicePrincipal}
Operation ID: getServicePrincipal
Effect: read
Confirmation: never
Required privilege: MANAGE_PLATFORM
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
servicePrincipal |
path | Yes | string |
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
Update a service principal
PATCH /api/v1/service-principals/{servicePrincipal}
Operation ID: updateServicePrincipal
Effect: write
Confirmation: conditional
Required privilege: MANAGE_PLATFORM
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
servicePrincipal |
path | Yes | string | |
If-Match |
header | Yes | string |
Request body
Content types: application/json.
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
List service-principal secrets
GET /api/v1/service-principals/{servicePrincipal}/secrets
Operation ID: listServicePrincipalSecrets
Effect: read
Confirmation: never
Required privilege: MANAGE_PLATFORM
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
servicePrincipal |
path | Yes | string | |
limit |
query | No | integer | |
pageToken |
query | No | string |
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
Create a service principal secret
POST /api/v1/service-principals/{servicePrincipal}/secrets
Operation ID: createServicePrincipalSecret
Effect: write
Confirmation: conditional
Required privilege: MANAGE_PLATFORM
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
servicePrincipal |
path | Yes | string | |
Idempotency-Key |
header | Yes | string |
Request body
Content types: application/json.
Responses
| Status | Description |
|---|---|
201 |
The request has succeeded and a new resource has been created as a result. |
Revoke a service principal secret
DELETE /api/v1/service-principals/{servicePrincipal}/secrets/{secret}
Operation ID: revokeServicePrincipalSecret
Effect: destructive
Confirmation: required
Required privilege: MANAGE_PLATFORM
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
servicePrincipal |
path | Yes | string | |
secret |
path | Yes | string |
Responses
| Status | Description |
|---|---|
204 |
There is no content to send for this request, but the headers may be useful. |
Get service-principal secret metadata
GET /api/v1/service-principals/{servicePrincipal}/secrets/{secret}
Operation ID: getServicePrincipalSecret
Effect: read
Confirmation: never
Required privilege: MANAGE_PLATFORM
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
servicePrincipal |
path | Yes | string | |
secret |
path | Yes | string |
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
Check multiple authorization decisions
POST /api/v1/workspaces/{workspace}/authorization-checks
Operation ID: checkAuthorizationBatch
Effect: write
Confirmation: conditional
Required privilege: USE_WORKSPACE
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace |
path | Yes | string |
Request body
Content types: application/json.
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
List data policies
GET /api/v1/workspaces/{workspace}/data-policies
Operation ID: listDataPolicies
Effect: read
Confirmation: never
Required privilege: MANAGE_GRANTS
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace |
path | Yes | string | |
objectType |
query | No | string | |
objectId |
query | No | string | |
includeInherited |
query | No | boolean | |
limit |
query | No | integer | |
pageToken |
query | No | string |
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
Create a data policy
POST /api/v1/workspaces/{workspace}/data-policies
Operation ID: createDataPolicy
Effect: write
Confirmation: conditional
Required privilege: MANAGE_GRANTS
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace |
path | Yes | string | |
Idempotency-Key |
header | Yes | string |
Request body
Content types: application/json.
Responses
| Status | Description |
|---|---|
201 |
The request has succeeded and a new resource has been created as a result. |
Delete a data policy
DELETE /api/v1/workspaces/{workspace}/data-policies/{policy}
Operation ID: deleteDataPolicy
Effect: destructive
Confirmation: required
Required privilege: MANAGE_GRANTS
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace |
path | Yes | string | |
policy |
path | Yes | string |
Responses
| Status | Description |
|---|---|
204 |
There is no content to send for this request, but the headers may be useful. |
Get a data policy
GET /api/v1/workspaces/{workspace}/data-policies/{policy}
Operation ID: getDataPolicy
Effect: read
Confirmation: never
Required privilege: MANAGE_GRANTS
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace |
path | Yes | string | |
policy |
path | Yes | string |
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
Update a data policy
PATCH /api/v1/workspaces/{workspace}/data-policies/{policy}
Operation ID: updateDataPolicy
Effect: write
Confirmation: conditional
Required privilege: MANAGE_GRANTS
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace |
path | Yes | string | |
policy |
path | Yes | string | |
If-Match |
header | Yes | string |
Request body
Content types: application/json.
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
List effective privileges
GET /api/v1/workspaces/{workspace}/effective-privileges
Operation ID: listEffectivePrivileges
Effect: read
Confirmation: never
Required privilege: USE_WORKSPACE
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace |
path | Yes | string | |
objectType |
query | No | string | |
objectId |
query | No | string |
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
List grants
GET /api/v1/workspaces/{workspace}/grants
Operation ID: listGrants
Effect: read
Confirmation: never
Required privilege: MANAGE_GRANTS
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace |
path | Yes | string | |
objectType |
query | No | string | |
objectId |
query | No | string | |
includeInherited |
query | No | boolean | |
limit |
query | No | integer | |
pageToken |
query | No | string |
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
Create a grant
POST /api/v1/workspaces/{workspace}/grants
Operation ID: createGrant
Effect: write
Confirmation: conditional
Required privilege: MANAGE_GRANTS
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace |
path | Yes | string | |
Idempotency-Key |
header | Yes | string |
Request body
Content types: application/json.
Responses
| Status | Description |
|---|---|
201 |
The request has succeeded and a new resource has been created as a result. |
Delete a grant
DELETE /api/v1/workspaces/{workspace}/grants/{grant}
Operation ID: deleteGrant
Effect: destructive
Confirmation: required
Required privilege: MANAGE_GRANTS
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace |
path | Yes | string | |
grant |
path | Yes | string |
Responses
| Status | Description |
|---|---|
204 |
There is no content to send for this request, but the headers may be useful. |
Get an object privilege grant
GET /api/v1/workspaces/{workspace}/grants/{grant}
Operation ID: getGrant
Effect: read
Confirmation: never
Required privilege: MANAGE_GRANTS
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace |
path | Yes | string | |
grant |
path | Yes | string |
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
Update an object privilege grant
PATCH /api/v1/workspaces/{workspace}/grants/{grant}
Operation ID: updateGrant
Effect: write
Confirmation: conditional
Required privilege: MANAGE_GRANTS
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace |
path | Yes | string | |
grant |
path | Yes | string | |
If-Match |
header | Yes | string |
Request body
Content types: application/json.
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
List groups
GET /api/v1/workspaces/{workspace}/groups
Operation ID: listGroups
Effect: read
Confirmation: never
Required privilege: MANAGE_GRANTS
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace |
path | Yes | string | |
limit |
query | No | integer | |
pageToken |
query | No | string |
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
Create a group
POST /api/v1/workspaces/{workspace}/groups
Operation ID: createGroup
Effect: write
Confirmation: conditional
Required privilege: MANAGE_GRANTS
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace |
path | Yes | string | |
Idempotency-Key |
header | Yes | string |
Request body
Content types: application/json.
Responses
| Status | Description |
|---|---|
201 |
The request has succeeded and a new resource has been created as a result. |
Delete a group
DELETE /api/v1/workspaces/{workspace}/groups/{group}
Operation ID: deleteGroup
Effect: destructive
Confirmation: required
Required privilege: MANAGE_GRANTS
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace |
path | Yes | string | |
group |
path | Yes | string |
Responses
| Status | Description |
|---|---|
204 |
There is no content to send for this request, but the headers may be useful. |
Get a group
GET /api/v1/workspaces/{workspace}/groups/{group}
Operation ID: getGroup
Effect: read
Confirmation: never
Required privilege: MANAGE_GRANTS
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace |
path | Yes | string | |
group |
path | Yes | string |
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
Update a group
PATCH /api/v1/workspaces/{workspace}/groups/{group}
Operation ID: updateGroup
Effect: write
Confirmation: conditional
Required privilege: MANAGE_GRANTS
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace |
path | Yes | string | |
group |
path | Yes | string | |
If-Match |
header | Yes | string |
Request body
Content types: application/json.
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
List group members
GET /api/v1/workspaces/{workspace}/groups/{group}/members
Operation ID: listGroupMembers
Effect: read
Confirmation: never
Required privilege: MANAGE_GRANTS
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace |
path | Yes | string | |
group |
path | Yes | string | |
limit |
query | No | integer | |
pageToken |
query | No | string |
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
Remove a group member
DELETE /api/v1/workspaces/{workspace}/groups/{group}/members/{principal}
Operation ID: removeGroupMember
Effect: destructive
Confirmation: required
Required privilege: MANAGE_GRANTS
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace |
path | Yes | string | |
group |
path | Yes | string | |
principal |
path | Yes | string |
Responses
| Status | Description |
|---|---|
204 |
There is no content to send for this request, but the headers may be useful. |
Add a group member
PUT /api/v1/workspaces/{workspace}/groups/{group}/members/{principal}
Operation ID: addGroupMember
Effect: idempotent-write
Confirmation: conditional
Required privilege: MANAGE_GRANTS
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace |
path | Yes | string | |
group |
path | Yes | string | |
principal |
path | Yes | string |
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
Transfer object ownership
POST /api/v1/workspaces/{workspace}/ownership
Operation ID: transferOwnership
Effect: write
Confirmation: conditional
Required privilege: MANAGE_ITEM
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace |
path | Yes | string | |
Idempotency-Key |
header | Yes | string |
Request body
Content types: application/json.
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
List role bindings
GET /api/v1/workspaces/{workspace}/role-bindings
Operation ID: listRoleBindings
Effect: read
Confirmation: never
Required privilege: MANAGE_GRANTS
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace |
path | Yes | string | |
subjectType |
query | No | string | |
subjectId |
query | No | string | |
role |
query | No | string | |
limit |
query | No | integer | |
pageToken |
query | No | string |
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
Create a role binding
POST /api/v1/workspaces/{workspace}/role-bindings
Operation ID: createRoleBinding
Effect: write
Confirmation: conditional
Required privilege: MANAGE_GRANTS
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace |
path | Yes | string | |
Idempotency-Key |
header | Yes | string |
Request body
Content types: application/json.
Responses
| Status | Description |
|---|---|
201 |
The request has succeeded and a new resource has been created as a result. |
Delete a role binding
DELETE /api/v1/workspaces/{workspace}/role-bindings/{binding}
Operation ID: deleteRoleBinding
Effect: destructive
Confirmation: required
Required privilege: MANAGE_GRANTS
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace |
path | Yes | string | |
binding |
path | Yes | string |
Responses
| Status | Description |
|---|---|
204 |
There is no content to send for this request, but the headers may be useful. |
Get a workspace role binding
GET /api/v1/workspaces/{workspace}/role-bindings/{binding}
Operation ID: getRoleBinding
Effect: read
Confirmation: never
Required privilege: MANAGE_GRANTS
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace |
path | Yes | string | |
binding |
path | Yes | string |
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
Update a role binding
PATCH /api/v1/workspaces/{workspace}/role-bindings/{binding}
Operation ID: updateRoleBinding
Effect: write
Confirmation: conditional
Required privilege: MANAGE_GRANTS
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace |
path | Yes | string | |
binding |
path | Yes | string | |
If-Match |
header | Yes | string |
Request body
Content types: application/json.
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
List workspace roles
GET /api/v1/workspaces/{workspace}/roles
Operation ID: listWorkspaceRoles
Effect: read
Confirmation: never
Required privilege: MANAGE_GRANTS
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace |
path | Yes | string | |
limit |
query | No | integer | |
pageToken |
query | No | string |
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
Common error responses
These error responses apply to every operation on this page.
| Status | Description |
|---|---|
400 |
The server could not understand the request due to invalid syntax. |
401 |
Access is unauthorized. |
403 |
Access is forbidden. |
404 |
The server cannot find the requested resource. |
409 |
The request conflicts with the current state of the server. |
412 |
Precondition failed. |
413 |
Client error |
415 |
Client error |
422 |
Client error |
429 |
Client error |
500 |
Server error |
502 |
Server error |
503 |
Service unavailable. |