User privilege assignment API — grant, deny, and audit

Grant, deny, and revoke direct user privileges in Alphabet. View effective privilege sets and audit history per user. Requires PrivilegeManagers policy.

In addition to role-based privileges, you can assign or deny privileges directly to individual users. This is useful when a user needs a specific permission that is not covered by their roles, or when you need to block access to a privilege that their role would otherwise grant. Direct denies override any role-based grants during privilege evaluation — a deny on a user will always win regardless of what roles the user belongs to.

---

Admin endpoints

The following endpoints require the PrivilegeManagers authorization policy.

---

Assign a direct privilege to a user

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

Creates a direct allow or deny privilege assignment for a user. Use the effect field to control whether the assignment grants or blocks the privilege.

Path parameters

userId · string (UUID) · required

The ID of the user to assign the privilege to.

Request body

privilegeId · string (UUID) · required

The ID of the privilege to assign.

effect · string · required

The effect of this assignment. Accepted values:

• Allow — explicitly grants the privilege to this user, in addition to any role-based grants.
• Deny — explicitly blocks the privilege for this user, overriding any role-based grants.

expiresAt · string (ISO 8601 datetime)

Optional expiration timestamp. When omitted, the assignment does not expire.

reason · string

Free-text justification for the assignment. Stored with the audit record.

Responses

200 OK

The assignment was created successfully.

400 Bad Request · ProblemDetails

Show ProblemDetails fields

title · string

Short error summary.

detail · string

Detailed error message.

Example — assigning a deny

curl --request POST \
  --url https://your-api.example.com/api/v1/users/c3d4e5f6-a7b8-9012-cdef-012345678901/privileges \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "privilegeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "effect": "Deny",
    "expiresAt": null,
    "reason": "User is under access review pending investigation."
  }'

---

Get effective privileges for a user

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

Returns the fully evaluated privilege set for the specified user. The result combines role-based grants, direct user grants, direct user denies, and any composite policies into a single resolved list.

Path parameters

userId · string (UUID) · required

The ID of the user to evaluate.

Response — 200 OK

(root) · UserEffectivePrivilegeDto[]

Show UserEffectivePrivilegeDto fields

privilegeName · string

Dot-notation privilege name.

isGranted · boolean

Whether the privilege is currently active for this user after all rules have been applied.

source · string

Origin of the resolved grant or deny, for example Role, DirectGrant, or DirectDeny.

Example

curl --request GET \
  --url https://your-api.example.com/api/v1/users/c3d4e5f6-a7b8-9012-cdef-012345678901/privileges/effective \
  --header 'Authorization: Bearer <token>'

[
  {
    "privilegeName": "report.export",
    "isGranted": false,
    "source": "DirectDeny"
  },
  {
    "privilegeName": "report.view",
    "isGranted": true,
    "source": "Role"
  }
]

---

Revoke a direct privilege from a user

Revoking a direct assignment removes it from evaluation but preserves the full audit trail. The historical record of the assignment is not deleted.

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

Removes a direct privilege assignment (allow or deny) from the specified user.

Path parameters

userId · string (UUID) · required

The ID of the user.

privilegeId · string (UUID) · required

The ID of the privilege assignment to revoke.

Responses

200 OK

The assignment was revoked successfully.

400 Bad Request · ProblemDetails

The revocation failed, for example because no matching assignment exists.

---

Get privilege audit history for a user

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

Returns a paginated list of privilege events for the specified user, including assignments, revocations, and evaluation decisions.

Path parameters

userId · string (UUID) · required

The ID of the user to retrieve audit history for.

Query parameters

take · integer · default: "100"

Maximum number of audit records to return. Values below 1 are coerced to 100.

skip · integer · default: "0"

Number of records to skip for pagination. Values below 0 are coerced to 0.

Response — 200 OK

(root) · PrivilegeAuditLogDto[]

Show PrivilegeAuditLogDto fields

action · string

The type of event, for example Assigned, Revoked, or Evaluated.

privilegeName · string

Name of the privilege involved in the event.

performedAt · string (ISO 8601 datetime)

Timestamp when the event occurred.

performedBy · string

Identity of the actor who triggered the event.

---

Assign a policy directly to a user

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

Associates a composite privilege policy directly with a user, outside of role membership.

Path parameters

userId · string (UUID) · required

The ID of the user 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 assigned to the user successfully.

400 Bad Request · ProblemDetails

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

---

Self-service endpoints

The following endpoints require only an authenticated user (Bearer token). No elevated policy is needed.

---

Get your own effective privileges

GET /api/v1/users/me/privileges

Returns the calling user’s current effective privilege set after all role, direct user, and policy rules have been applied. Use this to build permission-aware UIs that adapt to what the authenticated user can actually do.

Response — 200 OK

(root) · UserEffectivePrivilegeDto[]

Same structure as the admin effective privileges response. See Get effective privileges for a user above.

---

Request temporary privilege access

POST /api/v1/users/me/privilege-requests

Submits a request for a specific privilege for a limited time period. The request enters an approval workflow before any access is granted.

Request body

privilegeId · string (UUID) · required

The ID of the privilege you are requesting.

reason · string · required

Business justification for the access request. Required for audit purposes.

requestedDurationDays · integer · required

Number of days you need this privilege. The approver may grant a shorter duration.

approverEmail · string

Optional email address of a specific approver. When omitted, the request is routed through the default approval workflow.

Responses

201 Created · string (UUID)

The ID of the newly created privilege request. Use this ID to track approval status.

400 Bad Request · ProblemDetails

The request creation failed, for example because the privilege ID is invalid.