Privilege catalog API — create and manage permissions

API reference for Alphabet privilege catalog endpoints: create, list, update, delete privileges, manage categories, and create composite policies.

The privilege catalog API lets you define and manage the permissions available in your system. Use these endpoints to create fine-grained privileges, organize them into categories, and group them into reusable composite policies. All endpoints in this section require the PrivilegeManagers authorization policy. Pass a valid Bearer token in the Authorization header for every request.

---

Create a privilege

Categories specified in the category field are created automatically if they do not already exist.

POST /api/v1/privileges

Defines a new privilege that can later be assigned to roles, users, or composite policies.

Request body

name · string · required

Unique, immutable identifier for the privilege. Use dot-notation namespacing to keep names readable and collision-free — for example, report.export or users.invite.

displayName · string

Human-readable label shown in management UIs.

description · string

Plain-text explanation of what this privilege grants.

category · string

Name of the category to place this privilege in. Created automatically when it does not exist.

resourceType · string

The resource type this privilege applies to, for example Report or User.

actions · string[]

List of actions this privilege covers, for example ["read", "export"].

isGlobal · boolean

When true, this privilege applies across all tenants or organizational scopes.

dependsOn · string[]

Array of privilege IDs (UUID format) that must also be granted for this privilege to be effective.

attributes · object

Arbitrary key-value metadata for this privilege. Use it to attach custom properties consumed by your application logic.

Responses

201 Created · string (UUID)

The ID of the newly created privilege.

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/privileges \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "report.export",
    "displayName": "Export Reports",
    "description": "Allows the user to export report data to file formats.",
    "category": "Reporting",
    "resourceType": "Report",
    "actions": ["read", "export"],
    "isGlobal": false,
    "dependsOn": [],
    "attributes": { "maxExportRows": 50000 }
  }'

"3fa85f64-5717-4562-b3fc-2c963f66afa6"

---

List privileges

GET /api/v1/privileges

Returns a paginated list of privilege definitions. You can filter by category, search by name, and optionally include deprecated privileges.

Query parameters

pageNumber · integer · default: "1"

Page index to retrieve. Values below 1 are coerced to 1.

pageSize · integer · default: "50"

Number of items per page. Values below 1 are coerced to 50.

category · string

Filter results to privileges belonging to this category name.

search · string

Full-text search term matched against privilege names and display names.

includeDeprecated · boolean

Set to true to include soft-deleted (deprecated) privileges in results. Defaults to false.

Response — 200 OK

items · PrivilegeDto[]

Show PrivilegeDto fields

id · string (UUID)

Unique privilege identifier.

name · string

Immutable dot-notation privilege name.

displayName · string

Human-readable label.

categoryName · string

Name of the assigned category, if any.

isDeprecated · boolean

Whether this privilege has been soft-deleted.

isGlobal · boolean

Whether this privilege spans all organizational scopes.

totalCount · integer

Total number of matching privileges across all pages.

pageNumber · integer

Current page index.

pageSize · integer

Number of items returned per page.

Example

curl --request GET \
  --url 'https://your-api.example.com/api/v1/privileges?pageNumber=1&pageSize=20&category=Reporting' \
  --header 'Authorization: Bearer <token>'

{
  "items": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "report.export",
      "displayName": "Export Reports",
      "categoryName": "Reporting",
      "isDeprecated": false,
      "isGlobal": false
    }
  ],
  "totalCount": 1,
  "pageNumber": 1,
  "pageSize": 20
}

---

Get a privilege

GET /api/v1/privileges/{privilegeId}

Returns full metadata for a single privilege, including its dependencies, actions, and attributes.

Path parameters

privilegeId · string (UUID) · required

The ID of the privilege to retrieve.

Responses

200 OK · PrivilegeDto

Full privilege detail. Includes all fields from the list response plus dependencies, actions, and attributes.

404 Not Found · ProblemDetails

Returned when no privilege with the given ID exists.

---

Update a privilege

The name field is immutable and cannot be changed after creation. Omit it from the request body.

PUT /api/v1/privileges/{privilegeId}

Updates the mutable metadata fields of an existing privilege.

Path parameters

privilegeId · string (UUID) · required

The ID of the privilege to update.

Request body

displayName · string

Updated human-readable label.

description · string

Updated description.

category · string

Updated category name.

resourceType · string

Updated resource type.

actions · string[]

Replacement set of actions. This overwrites the existing actions list.

dependsOn · string[]

Replacement set of dependency privilege IDs (UUID format).

attributes · object

Replacement attribute map.

Responses

200 OK

The privilege was updated successfully.

400 Bad Request · ProblemDetails

Validation failed or the update was rejected.

---

Delete a privilege

Setting hardDelete=true permanently removes the privilege record. This operation fails if the privilege is currently assigned to any role, user, or policy.

DELETE /api/v1/privileges/{privilegeId}?hardDelete=false

Deprecates or permanently removes a privilege.

Path parameters

privilegeId · string (UUID) · required

The ID of the privilege to delete.

Query parameters

hardDelete · boolean · default: "false"

When false (default), the privilege is soft-deleted and marked deprecated. When true, the privilege is permanently removed. Hard delete fails if the privilege is still assigned anywhere.

Responses

200 OK

The privilege was deprecated or deleted successfully.

400 Bad Request · ProblemDetails

Returned when a hard delete is blocked because the privilege is still assigned.

---

Create a category

POST /api/v1/privileges/categories

Creates a named category to organize privileges in the catalog. Categories support nesting through the optional parentCategoryId field.

Request body

name · string · required

Unique name for the category.

description · string

Plain-text description of what this category contains.

parentCategoryId · string (UUID)

ID of the parent category. Omit this field to create a top-level category.

sortOrder · integer

Integer sort position used when rendering category lists in UIs.

Responses

201 Created · string (UUID)

The ID of the newly created category.

400 Bad Request · ProblemDetails

Category creation failed due to a validation error.

---

List categories

GET /api/v1/privileges/categories

Returns the full category tree. The response is a hierarchical structure you can use to build category navigation or filtering UIs.

Response — 200 OK

(root) · PrivilegeCategoryDto[]

Show PrivilegeCategoryDto fields

id · string (UUID)

Category identifier.

name · string

Category name.

description · string

Category description.

parentCategoryId · string (UUID)

ID of the parent category, or null for top-level categories.

sortOrder · integer

Display sort order.

children · PrivilegeCategoryDto[]

Nested child categories.

---

Move a privilege to a different category

PATCH /api/v1/privileges/{privilegeId}/category

Reassigns an existing privilege to a different category.

Path parameters

privilegeId · string (UUID) · required

The ID of the privilege to move.

Request body

categoryId · string (UUID) · required

The ID of the target category.

Responses

200 OK

The privilege was moved successfully.

400 Bad Request · ProblemDetails

The move failed, for example because the target category does not exist.

---

Create a composite policy

POST /api/v1/privileges/policies

Creates a reusable policy that bundles multiple privileges together. When you assign a policy to a role or user, all privileges in the policy are evaluated together according to the specified condition.

Request body

name · string · required

Unique name for the policy.

description · string

Plain-text explanation of what this policy grants.

privileges · string[] · required

Array of privilege IDs (UUID format) to include in this policy.

condition · string · required

Evaluation rule for the policy. Accepted values:

• AllRequired — the user must have every privilege in the policy for the policy to evaluate as granted.
• AnyRequired — the user must have at least one privilege in the policy for the policy to evaluate as granted.

Responses

201 Created · string (UUID)

The ID of the newly created policy.

400 Bad Request · ProblemDetails

Policy creation failed due to a validation error.