Skip to content

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 ​

StatusCodeDetail
400subject_kind and subject_id are requiredInvalid Request
401authentication failedUnauthorized
403insufficient_permissionsForbidden
404the requested resource was not foundNot Found
500authentication service unavailableInternal 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) ​

FieldTypeRequired
conditionstringNo
expires_atstring (date-time)No
role_idstringYes
subject_idstringYes
subject_kindstringYes
team_idobjectNo
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 ​

StatusCodeDetail
400binding team_id does not match role team_idInvalid Request; Invalid Request; Invalid Request; Invalid Request; Invalid Request
400request body must be valid JSONInvalid Request; Invalid Request; Invalid Request; Invalid Request; Invalid Request
400team baseline bindings cannot expireInvalid Request; Invalid Request; Invalid Request; Invalid Request; Invalid Request
400team baseline requires matching team_id and subject_idInvalid Request; Invalid Request; Invalid Request; Invalid Request; Invalid Request
400team baseline role must belong to the same teamInvalid Request; Invalid Request; Invalid Request; Invalid Request; Invalid Request
401authentication failedUnauthorized
403insufficient_permissionsForbidden; Step-up Required
403step_up_requiredForbidden; Step-up Required
404the requested resource was not foundNot Found
409a team baseline binding already existsConflict; Conflict
409the resource already existsConflict; Conflict
422condition could not be compiledInvalid Condition
500authentication service unavailableInternal 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 ​

ParameterDescription
idPath parameter.

Responses ​

  • 204 — No Content

Errors ​

StatusCodeDetail
401authentication failedUnauthorized
403insufficient_permissionsForbidden; Step-up Required
403step_up_requiredForbidden; Step-up Required
404the requested resource was not foundNot Found
500authentication service unavailableInternal 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 ​

ParameterDescription
idPath 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 ​

StatusCodeDetail
401authentication failedUnauthorized
403insufficient_permissionsForbidden
404the requested resource was not foundNot Found
500authentication service unavailableInternal 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 ​

ParameterDescription
idPath parameter.

Request body (application/json) ​

FieldTypeRequired
conditionobjectYes
expires_atobjectYes
role_idobjectYes
subject_idobjectYes
subject_kindobjectYes
team_idobjectYes
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 ​

StatusCodeDetail
400binding identity and scope cannot be changedInvalid Request; Invalid Request; Invalid Request; Invalid Request
400binding team_id does not match role team_idInvalid Request; Invalid Request; Invalid Request; Invalid Request
400request body must be valid JSONInvalid Request; Invalid Request; Invalid Request; Invalid Request
400team baseline role must belong to the same teamInvalid Request; Invalid Request; Invalid Request; Invalid Request
401authentication failedUnauthorized
403insufficient_permissionsForbidden; Step-up Required
403step_up_requiredForbidden; Step-up Required
404the requested resource was not foundNot Found
422condition could not be compiledInvalid Condition
500authentication service unavailableInternal Server Error