Appearance
Bindings API Reference
GET /bindings/
List role bindings for a subject
Lists a user's or group's role assignments or a team's singleton baseline for the required subject_kind and subject_id, ordered by ascending binding ID. iam:bindings:team authorizes group/team queries for an active target team; user-wide queries require platform iam:bindings:any. See REST pagination for the shared collection contract.
Required permission — iam:bindings:any (or iam:bindings:team scoped to the target team)
Responses
- 200 — Successful response
json
{
"items": [
{
"condition": "resource.team_id == \"01J8Z3TEAM000000000000001\"",
"id": "01J8Z3BIND000000000000001",
"role_id": "01J8Z3ROLE000000000000001",
"subject_id": "01J8Z3TEAM000000000000001",
"subject_kind": "team",
"team_id": "01J8Z3TEAM000000000000001"
}
],
"next_cursor": ""
}Errors
| Status | Code | Detail |
|---|---|---|
| 400 | subject_kind and subject_id are required | Invalid Request |
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden |
| 404 | the requested resource was not found | Not Found |
| 500 | authentication service unavailable | Internal Server Error |
POST /bindings/
Create a role binding
Use to assign a role to a user or group, or create one team's singleton baseline with subject_kind=team and subject_id equal to the team ID. For a baseline, team_id may be omitted/inferred or must equal subject_id; the role may be platform-scoped or belong to that team, but never a foreign team. Conditions and deny permissions are allowed, and expires_at is forbidden. Every user with at least one unexpired membership in a group within the active team inherits the role; the baseline stops applying after the user's last such membership expires or is removed. A duplicate baseline returns 409. User/group bindings retain expiry semantics. A successful create returns 201. Team-bound grants stay confined to their active resource team, including keys ending in :any. A matching team-baseline deny defeats a matching platform allow for an eligible member's resource in that team; an outsider, including a platform administrator without active membership, does not inherit the baseline deny and retains independent platform grants.
Required permission — iam:bindings:any (or iam:bindings:team scoped to the target team) Requires a user bearer with positive auth_time or step_up_time no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Otherwise returns 403 step_up_required.
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| condition | string | No |
| expires_at | string (date-time) | No |
| role_id | string | Yes |
| subject_id | string | Yes |
| subject_kind | string | Yes |
| team_id | object | No |
json
{
"condition": "resource.team_id == \"01J8Z3TEAM000000000000001\"",
"role_id": "01J8Z3ROLE000000000000001",
"subject_id": "01J8Z3TEAM000000000000001",
"subject_kind": "team",
"team_id": "01J8Z3TEAM000000000000001"
}Responses
- 201 — Successful response
json
{
"condition": "resource.team_id == \"01J8Z3TEAM000000000000001\"",
"id": "01J8Z3BIND000000000000001",
"role_id": "01J8Z3ROLE000000000000001",
"subject_id": "01J8Z3TEAM000000000000001",
"subject_kind": "team",
"team_id": "01J8Z3TEAM000000000000001"
}Errors
| Status | Code | Detail |
|---|---|---|
| 400 | binding team_id does not match role team_id | Invalid Request; Invalid Request; Invalid Request; Invalid Request; Invalid Request |
| 400 | request body must be valid JSON | Invalid Request; Invalid Request; Invalid Request; Invalid Request; Invalid Request |
| 400 | team baseline bindings cannot expire | Invalid Request; Invalid Request; Invalid Request; Invalid Request; Invalid Request |
| 400 | team baseline requires matching team_id and subject_id | Invalid Request; Invalid Request; Invalid Request; Invalid Request; Invalid Request |
| 400 | team baseline role must belong to the same team | Invalid Request; Invalid Request; Invalid Request; Invalid Request; Invalid Request |
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden; Step-up Required |
| 403 | step_up_required | Forbidden; Step-up Required |
| 404 | the requested resource was not found | Not Found |
| 409 | a team baseline binding already exists | Conflict; Conflict |
| 409 | the resource already exists | Conflict; Conflict |
| 422 | condition could not be compiled | Invalid Condition |
| 500 | authentication service unavailable | Internal Server Error |
DELETE /bindings/{id}
Delete a role binding
Use to remove a user or group role assignment or a team's singleton baseline. iam:bindings:team can remove bindings only for its active target team; independent platform iam:bindings:any can maintain disabled teams. The deletion is audited and affected users' permission versions are invalidated, including every member inheriting the baseline.
Required permission — iam:bindings:any (or iam:bindings:team scoped to the target team) Requires a user bearer with positive auth_time or step_up_time no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Otherwise returns 403 step_up_required.
Path parameters
| Parameter | Description |
|---|---|
| id | Path parameter. |
Responses
- 204 — No Content
Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden; Step-up Required |
| 403 | step_up_required | Forbidden; Step-up Required |
| 404 | the requested resource was not found | Not Found |
| 500 | authentication service unavailable | Internal Server Error |
GET /bindings/{id}
Get a role binding
Use to retrieve one binding by ID, including its persisted team scope and subject. A binding with team_id: null is platform-scoped; team-targeted bindings are authorized against their existing team.
Required permission — iam:bindings:any (or iam:bindings:team scoped to the target team) Requires iam:bindings:any, or an applicable iam:bindings:team grant for the binding's active target team; platform bindings (team_id: null) require iam:bindings:any. Reads do not require step-up authentication.
Path parameters
| Parameter | Description |
|---|---|
| id | Path parameter. |
Responses
- 200 — Successful response
json
{
"condition": "resource.team_id == \"01J8Z3TEAM000000000000001\"",
"id": "01J8Z3BIND000000000000001",
"role_id": "01J8Z3ROLE000000000000001",
"subject_id": "01J8Z3TEAM000000000000001",
"subject_kind": "team",
"team_id": "01J8Z3TEAM000000000000001"
}Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden |
| 404 | the requested resource was not found | Not Found |
| 500 | authentication service unavailable | Internal Server Error |
PATCH /bindings/{id}
Update a role binding
Use to replace role_id and/or condition on an existing binding. Omitted values remain unchanged; send condition:null to clear the condition. subject_kind, subject_id, team_id, and expires_at are immutable; team baselines remain permanent and accept only a platform-scoped or same-team role. iam:bindings:team can update bindings only for its active target team; independent platform iam:bindings:any can maintain disabled teams. A team-scoped binding can only target its active team and cannot turn a :any key into platform access.
Required permission — iam:bindings:any (or iam:bindings:team scoped to the target team) Requires a user bearer with positive auth_time or step_up_time no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Otherwise returns 403 step_up_required.
Path parameters
| Parameter | Description |
|---|---|
| id | Path parameter. |
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| condition | object | Yes |
| expires_at | object | Yes |
| role_id | object | Yes |
| subject_id | object | Yes |
| subject_kind | object | Yes |
| team_id | object | Yes |
json
{
"condition": "resource.attrs[\"region\"] == \"us-east-1\"",
"role_id": "01J8Z3ROLE000000000000002"
}Responses
- 200 — Successful response
json
{
"condition": "resource.attrs[\"region\"] == \"us-east-1\"",
"id": "01J8Z3BIND000000000000001",
"role_id": "01J8Z3ROLE000000000000002",
"subject_id": "01J8Z3TEAM000000000000001",
"subject_kind": "team",
"team_id": "01J8Z3TEAM000000000000001"
}Errors
| Status | Code | Detail |
|---|---|---|
| 400 | binding identity and scope cannot be changed | Invalid Request; Invalid Request; Invalid Request; Invalid Request |
| 400 | binding team_id does not match role team_id | Invalid Request; Invalid Request; Invalid Request; Invalid Request |
| 400 | request body must be valid JSON | Invalid Request; Invalid Request; Invalid Request; Invalid Request |
| 400 | team baseline role must belong to the same team | Invalid Request; Invalid Request; Invalid Request; Invalid Request |
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden; Step-up Required |
| 403 | step_up_required | Forbidden; Step-up Required |
| 404 | the requested resource was not found | Not Found |
| 422 | condition could not be compiled | Invalid Condition |
| 500 | authentication service unavailable | Internal Server Error |