Privilege evaluation API — check access at runtime

Check whether the authenticated user has a specific privilege in Alphabet, or batch-check multiple privileges in a single API call.

Use these endpoints to check at runtime whether the current user has access to a specific capability. The evaluation endpoints resolve the caller’s full effective privilege set — combining role grants, direct user grants, direct denies, and policies — and return the result in a format optimized for front-end permission gating. Both evaluation endpoints require only an authenticated user (Bearer token); no elevated policy is needed.

---

Check a single privilege

GET /api/v1/auth/check-privilege/{privilegeName}

Evaluates a single privilege for the authenticated user and returns whether it is currently granted, along with the source that determined the result.

Path parameters

privilegeName · string · required

The dot-notation name of the privilege to check — for example, report.export. This is the same name field used when creating a privilege.

Responses

200 OK · PrivilegeCheckResultDto

Show PrivilegeCheckResultDto fields

hasPrivilege · boolean

Whether the authenticated user currently holds this privilege.

privilegeName · string

The privilege name that was evaluated, echoed back for confirmation.

source · string

The rule source that produced the result, for example Role, DirectGrant, or DirectDeny.

400 Bad Request · ProblemDetails

Returned when the current user’s identity cannot be resolved from the Bearer token. Ensure the token is valid and contains a subject claim.

Example

curl --request GET \
  --url https://your-api.example.com/api/v1/auth/check-privilege/report.export \
  --header 'Authorization: Bearer <token>'

{
  "hasPrivilege": true,
  "privilegeName": "report.export",
  "source": "Role"
}

---

Batch-check privileges

Use this endpoint during application initialization to load all permission states in a single round trip, rather than issuing individual checks per feature.

POST /api/v1/auth/check-privileges

Evaluates multiple privilege names for the authenticated user in a single request. Returns a dictionary mapping each privilege name to a boolean indicating whether it is granted.

Request body

privileges · string[] · required

Array of dot-notation privilege names to evaluate — for example, ["report.export", "users.invite", "admin.access"].

Response — 200 OK

A flat dictionary where each key is a privilege name and the value is true if the authenticated user currently holds that privilege, or false if they do not.

{privilegeName} · boolean

true if the user holds this privilege; false otherwise. The response contains one entry per name submitted in the request body.

Example

curl --request POST \
  --url https://your-api.example.com/api/v1/auth/check-privileges \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "privileges": ["report.export", "users.invite", "admin.access"]
  }'

{
  "report.export": true,
  "users.invite": false,
  "admin.access": false
}

---

Admin analytics and audit

The following endpoints require the PrivilegeManagers authorization policy.

---

Get privilege analytics

GET /api/v1/admin/privileges/analytics

Returns privilege usage metrics to support governance reviews and access audits. Use this to identify unused privileges and track assignment trends over time.

Response — 200 OK

totalPrivileges · integer

Total number of privilege definitions in the catalog, including deprecated ones.

assignedCount · integer

Number of privileges that are currently assigned to at least one role, user, or policy.

unusedPrivileges · string[]

List of privilege names that exist in the catalog but are not assigned anywhere. These are candidates for cleanup.

recentActivity · object

Summary of recent assignment and revocation events. Structure varies by implementation.

---

Query privilege audit logs

GET /api/v1/admin/audit/privileges

Searches the privilege audit log across all users and privileges. All query parameters are optional and can be combined to narrow results.

Query parameters

userId · string (UUID)

Filter to events involving this user.

privilegeId · string (UUID)

Filter to events involving this privilege.

action · string

Filter to a specific action type, for example Assigned or Revoked.

from · string (ISO 8601 datetime)

Return only events that occurred on or after this timestamp.

to · string (ISO 8601 datetime)

Return only events that occurred on or before this timestamp.

take · integer · default: "100"

Maximum number of records to return.

skip · integer · default: "0"

Number of records to skip for pagination.

Response — 200 OK

(root) · PrivilegeAuditLogDto[]

Show PrivilegeAuditLogDto fields

action · string

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.

---

Export the privilege catalog

This endpoint returns up to 5,000 privileges in a single response. For very large catalogs, apply category or search filters on the List privileges endpoint instead of relying on the export for real-time queries.

GET /api/v1/admin/privileges/export?format=json

Downloads the full privilege catalog in JSON or CSV format for offline analysis, reporting, or governance reviews.

Query parameters

format · string · default: "json"

Output format. Accepted values:

• json — returns a JSON array of privilege objects.
• csv — returns a CSV file with columns Id, Name, DisplayName, Category, IsDeprecated, IsGlobal.

Response — 200 OK

The response body is either a JSON array or a CSV file depending on the format parameter. The Content-Type header is application/json for JSON and text/csv for CSV. When format=csv, the response includes a Content-Disposition header with the filename privileges.csv.

Example — CSV export

curl --request GET \
  --url 'https://your-api.example.com/api/v1/admin/privileges/export?format=csv' \
  --header 'Authorization: Bearer <token>' \
  --output privileges.csv

Example — JSON export

curl --request GET \
  --url 'https://your-api.example.com/api/v1/admin/privileges/export?format=json' \
  --header 'Authorization: Bearer <token>'