Role privilege assignment API — grant and revoke access

Assign, revoke, and bulk-manage privileges and policies for roles in Alphabet. All endpoints require the PrivilegeManagers policy.

Use these endpoints to grant privileges to roles. Every member of a role automatically inherits the role’s assigned privileges. Changes take effect immediately — there is no need to refresh sessions or re-authenticate. All endpoints in this section require the PrivilegeManagers authorization policy.

---

Assign privileges to a role

POST /api/v1/roles/{roleId}/privileges

Grants one or more privileges to the specified role. You can optionally set an expiration date after which the assignment is no longer active.

Path parameters

roleId · string (UUID) · required

The ID of the role to assign privileges to.

Request body

privilegeIds · string[] · required

Array of privilege IDs (UUID format) to grant to this role.

expiresAt · string (ISO 8601 datetime)

Optional expiration timestamp for all assignments in this request. When omitted, the assignments do not expire. Example: 2026-12-31T23:59:59Z.

Responses

200 OK

All specified privileges were assigned to the role successfully.

400 Bad Request · ProblemDetails

Show ProblemDetails fields

title · string

Short error summary.

detail · string

Detailed error message.

Example

curl --request POST \
  --url https://your-api.example.com/api/v1/roles/a1b2c3d4-e5f6-7890-abcd-ef1234567890/privileges \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "privilegeIds": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "7cb96e31-4829-4a71-a913-3d8051f12bcd"
    ],
    "expiresAt": "2026-12-31T23:59:59Z"
  }'

---

List privileges assigned to a role

GET /api/v1/roles/{roleId}/privileges

Returns all direct privilege assignments for a role, together with grant metadata and active status.

Path parameters

roleId · string (UUID) · required

The ID of the role to query.

Response — 200 OK

(root) · PrivilegeAssignmentDto[]

Show PrivilegeAssignmentDto fields

privilegeId · string (UUID)

ID of the assigned privilege.

privilegeName · string

Dot-notation name of the assigned privilege.

grantedAt · string (ISO 8601 datetime)

Timestamp when the assignment was created.

expiresAt · string (ISO 8601 datetime)

Expiration timestamp, or null if the assignment does not expire.

isActive · boolean

Whether the assignment is currently active. An assignment becomes inactive when it expires or is explicitly revoked.

---

Revoke a privilege from a role

Revoking an assignment deactivates it while preserving the audit record. The assignment is not permanently deleted.

DELETE /api/v1/roles/{roleId}/privileges/{privilegeId}

Deactivates a privilege assignment for the specified role.

Path parameters

roleId · string (UUID) · required

The ID of the role.

privilegeId · string (UUID) · required

The ID of the privilege to revoke.

Responses

200 OK

The assignment was deactivated successfully.

400 Bad Request · ProblemDetails

The revocation failed, for example because the assignment does not exist.

---

Bulk assign or revoke privileges across roles

POST /api/v1/roles/bulk/assign-privileges

Grants or revokes one or more privileges across multiple roles in a single request. Use this endpoint to efficiently manage permissions during role restructuring or onboarding.

Request body

roleIds · string[] · required

Array of role IDs (UUID format) to apply the operation to.

privilegeIds · string[] · required

Array of privilege IDs (UUID format) to grant or revoke.

operation · string · required

The operation to perform. Accepted values:

• Grant — adds the specified privileges to each role.
• Revoke — removes the specified privileges from each role.

expiresAt · string (ISO 8601 datetime)

Expiration timestamp applied to all new grant assignments. Ignored when operation is Revoke.

Responses

200 OK

The bulk operation completed successfully for all specified roles.

400 Bad Request · ProblemDetails

The operation failed. Partial results are not applied — the request is treated atomically.

Example

curl --request POST \
  --url https://your-api.example.com/api/v1/roles/bulk/assign-privileges \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "roleIds": [
      "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "b2c3d4e5-f6a7-8901-bcde-f01234567891"
    ],
    "privilegeIds": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ],
    "operation": "Grant",
    "expiresAt": null
  }'

---

Assign a policy to a role

POST /api/v1/roles/{roleId}/policies

Associates a composite privilege policy with a role. All privileges defined in the policy are then evaluated for every member of the role according to the policy’s condition.

Path parameters

roleId · string (UUID) · required

The ID of the role to assign the policy to.

Request body

policyId · string (UUID) · required

The ID of the composite privilege policy to assign.

expiresAt · string (ISO 8601 datetime)

Optional expiration timestamp for this policy assignment.

Responses

200 OK

The policy was associated with the role successfully.

400 Bad Request · ProblemDetails

The assignment failed, for example because the policy ID is invalid.