Assign and revoke privileges for roles and users in Alphabet

Grant and revoke privileges for roles or individual users in Alphabet, including bulk operations, policy assignments, and effective privilege lookups.

Alphabet lets you assign privileges at two levels: to roles, which affects every member of that role, and directly to individual users for fine-grained overrides. All assignment endpoints require membership in the Admin or PrivilegeManager role.

Role privilege assignments

Assign privileges to a role

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

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

{
  "privilegeIds": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "7cb96a15-8234-4873-c4fd-3e074f77bfb7"
  ],
  "expiresAt": "2025-12-31T00:00:00Z"
}

Field	Type	Required	Description
privilegeIds	GUID[]	Yes	One or more privilege IDs to grant to this role.
expiresAt	ISO 8601 datetime	No	Expiry for the assignment. Omit for a non-expiring grant.

curl -X POST "https://your-api/api/v1/roles/c3d4e5f6-1234-5678-abcd-ef9012345678/privileges" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "privilegeIds": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
    "expiresAt": "2025-12-31T00:00:00Z"
  }'

List privileges assigned to a role

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

Returns the current direct privilege assignments for the role, including grant metadata and active status.

curl -X GET "https://your-api/api/v1/roles/c3d4e5f6-1234-5678-abcd-ef9012345678/privileges" \
  -H "Authorization: Bearer {token}"

Revoke a privilege from a role

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

Deactivates the assignment. Role members lose this privilege the next time their effective privileges are evaluated (subject to cache TTL).

curl -X DELETE "https://your-api/api/v1/roles/c3d4e5f6-1234-5678-abcd-ef9012345678/privileges/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}"

Bulk grant or revoke across multiple roles

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

Apply the same privilege change across multiple roles in a single request. This is useful when rolling out a new privilege to a set of roles at once.

{
  "roleIds": [
    "c3d4e5f6-1234-5678-abcd-ef9012345678",
    "d4e5f6a7-2345-6789-bcde-fa0123456789"
  ],
  "privilegeIds": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ],
  "operation": "Grant",
  "expiresAt": "2025-12-31T00:00:00Z"
}

Field	Type	Required	Description
roleIds	GUID[]	Yes	Roles to apply the operation to.
privilegeIds	GUID[]	Yes	Privileges to grant or revoke.
operation	string	Yes	"Grant" or "Revoke".
expiresAt	ISO 8601 datetime	No	Expiry (applies to Grant operations only).

Assign a policy to a role

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

Associates a composite policy with a role. All members of the role inherit the policy’s privileges evaluated under the policy’s condition (AllRequired or AnyRequired).

{
  "policyId": "9b8a7c6d-5e4f-3a2b-1c0d-e9f8a7b6c5d4",
  "expiresAt": "2025-12-31T00:00:00Z"
}

Direct user assignments

Direct assignments let you grant or deny a specific privilege for a single user, independent of their roles. Use this for exceptions — granting a user a capability their role does not include, or blocking a capability their role would otherwise allow.

Assign a privilege directly to a user

POST /api/v1/users/{userId}/privileges

{
  "privilegeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "effect": "Allow",
  "expiresAt": "2025-06-30T00:00:00Z",
  "reason": "Temporary access for Q2 audit project."
}

Field	Type	Required	Description
privilegeId	GUID	Yes	The privilege to assign.
effect	string	Yes	"Allow" or "Deny".
expiresAt	ISO 8601 datetime	No	Expiry for this assignment.
reason	string	No	Reason for the assignment, recorded in the audit log.

A direct deny ("effect": "Deny") overrides any role-based allow for the same privilege. This takes effect immediately — the user’s cache is invalidated as soon as the assignment is saved.

Get a user’s effective privileges

GET /api/v1/users/{userId}/privileges/effective

Returns the fully resolved privilege set for a user after combining all role grants, direct user grants, policy grants, and direct user denies.

curl -X GET "https://your-api/api/v1/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890/privileges/effective" \
  -H "Authorization: Bearer {token}"

Use this endpoint to debug why a user does or does not have access to a particular capability.

Revoke a direct user privilege

DELETE /api/v1/users/{userId}/privileges/{privilegeId}

Removes the direct assignment (allow or deny) for this user and privilege. The audit trail is preserved.

curl -X DELETE "https://your-api/api/v1/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890/privileges/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}"

Assign a policy directly to a user

POST /api/v1/users/{userId}/policies

Associates a composite policy with a specific user outside of role membership.

{
  "policyId": "9b8a7c6d-5e4f-3a2b-1c0d-e9f8a7b6c5d4",
  "expiresAt": "2025-06-30T00:00:00Z"
}

Audit history

User-scoped audit log

GET /api/v1/users/{userId}/privileges/audit

Returns assignment, revocation, and evaluation events for a single user’s privilege history.

Query parameter	Default	Description
take	100	Maximum number of events to return.
skip	0	Number of events to skip (for pagination).

curl -X GET "https://your-api/api/v1/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890/privileges/audit?take=50&skip=0" \
  -H "Authorization: Bearer {token}"

Admin-level audit log

GET /api/v1/admin/audit/privileges

Searches privilege audit events across all users and privileges. Supports filtering by user, privilege, action type, and date range.

Query parameter	Type	Description
userId	GUID	Filter to events for a specific user.
privilegeId	GUID	Filter to events for a specific privilege.
action	string	Filter by action type (e.g., Granted, Revoked, Checked).
from	ISO 8601 datetime	Start of the date range.
to	ISO 8601 datetime	End of the date range.
take	integer	Maximum results (default: 100).
skip	integer	Offset for pagination (default: 0).

curl -X GET "https://your-api/api/v1/admin/audit/privileges?from=2025-01-01T00:00:00Z&to=2025-03-31T23:59:59Z&take=100" \
  -H "Authorization: Bearer {token}"

Analytics

GET /api/v1/admin/privileges/analytics

Returns usage metrics across the privilege catalog: which privileges are actively used, which are never evaluated, and assignment trend data. Use this for periodic governance reviews.

curl -X GET "https://your-api/api/v1/admin/privileges/analytics" \
  -H "Authorization: Bearer {token}"

Direct deny assignments take precedence over role-based allows. Reserve them for specific, audited exceptions — not as a substitute for removing role memberships.