Manage the Alphabet privilege catalog and policies

Create, update, and organize privileges and categories in Alphabet’s catalog. Build composite policies that group multiple permissions together.

The privilege catalog is the central registry of every permission that Alphabet knows about. Before you can assign a privilege to a role or user, it must exist in the catalog. All catalog management endpoints require membership in the Admin or PrivilegeManager role.

Creating a privilege

Send a POST request to /api/v1/privileges with the privilege definition. A successful response returns the new privilege’s GUID.

POST /api/v1/privileges

Request body

{
  "name": "report.export",
  "displayName": "Export Reports",
  "description": "Allows the user to export reports to external formats.",
  "category": "Reporting",
  "resourceType": "Report",
  "actions": ["export", "download"],
  "isGlobal": false,
  "dependsOn": [],
  "attributes": {
    "sensitivity": "high"
  }
}

Field	Type	Required	Description
name	string	Yes	Stable resource.action identifier. Immutable after creation.
displayName	string	Yes	Human-readable label shown in UIs.
description	string	No	Longer explanation of what this privilege grants.
category	string	No	Category name. Created automatically if it does not exist.
resourceType	string	No	The type of resource this privilege governs (e.g., Report).
actions	string[]	No	Specific actions covered (e.g., ["export", "download"]).
isGlobal	boolean	No	Whether the privilege applies across all tenants or resource scopes.
dependsOn	string[]	No	Names of privileges that must also be granted for this one to be effective.
attributes	object	No	Arbitrary key-value metadata for your application’s use.

Response

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

The response body is the newly created privilege GUID. The Location header points to /api/v1/privileges/{privilegeId}.

Categories named in category are created automatically if they do not already exist. To build a category hierarchy, create categories explicitly using the categories endpoint described below.

Browsing privileges

List all privileges

GET /api/v1/privileges

Query parameters

Parameter	Type	Default	Description
pageNumber	integer	1	Page to return (1-indexed).
pageSize	integer	50	Results per page.
category	string	—	Filter to privileges in this category.
search	string	—	Full-text search across name, display name, and description.
includeDeprecated	boolean	false	Include soft-deleted privileges in results.

Example request

curl -X GET "https://your-api/api/v1/privileges?pageNumber=1&pageSize=20&category=Reporting&search=export" \
  -H "Authorization: Bearer {token}"

Example response

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

Get a single privilege

GET /api/v1/privileges/{privilegeId}

Returns full privilege metadata including dependencies, actions, and category details.

curl -X GET "https://your-api/api/v1/privileges/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}"

Updating a privilege

PUT /api/v1/privileges/{privilegeId}

You can update any mutable field. Send only the fields you want to change.

{
  "displayName": "Export and Download Reports",
  "description": "Updated description for export and download capability.",
  "category": "Reporting",
  "resourceType": "Report",
  "actions": ["export", "download", "schedule"],
  "dependsOn": [],
  "attributes": {
    "sensitivity": "high",
    "requiresMfa": "true"
  }
}

The name field (e.g., report.export) is immutable. It is not accepted in update requests. If you need to rename a privilege, create a new one and migrate all existing assignments.

A successful update returns 200 OK with an empty body.

Deprecating or deleting a privilege

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

Query parameter	Default	Behavior
hardDelete=false	Yes	Soft-deletes (deprecates) the privilege. It is hidden from the default listing but preserved in the database for audit purposes.
hardDelete=true	No	Permanently deletes the privilege. Fails if the privilege is still assigned to any role or user.

# Soft-delete (default)
curl -X DELETE "https://your-api/api/v1/privileges/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}"

# Hard-delete
curl -X DELETE "https://your-api/api/v1/privileges/3fa85f64-5717-4562-b3fc-2c963f66afa6?hardDelete=true" \
  -H "Authorization: Bearer {token}"

A hard delete with hardDelete=true returns 400 Bad Request if any active assignments reference this privilege. Revoke all assignments before attempting a hard delete.

Categories

Categories let you organize the privilege catalog into logical domains. They support a parent-child hierarchy.

Create a category

POST /api/v1/privileges/categories

{
  "name": "Analytics",
  "description": "Privileges related to data analytics and reporting.",
  "parentCategoryId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "sortOrder": 2
}

Field	Type	Required	Description
name	string	Yes	Category display name.
description	string	No	Optional description.
parentCategoryId	GUID	No	Places this category under a parent to form a hierarchy.
sortOrder	integer	No	Display order relative to siblings.

Get the category tree

GET /api/v1/privileges/categories

Returns the full hierarchical tree of categories. Use this to populate category pickers or validate category names before creating privileges.

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

Move a privilege to a different category

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

{
  "categoryId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Composite policies

A policy groups multiple privileges under a single assignable unit. When you assign a policy to a role or user, all the policy’s privileges are evaluated together.

Create a policy

POST /api/v1/privileges/policies

{
  "name": "Reporting Full Access",
  "description": "Grants all reporting capabilities including export and scheduling.",
  "privileges": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "7cb96a15-8234-4873-c4fd-3e074f77bfb7"
  ],
  "condition": "AllRequired"
}

Field	Type	Required	Description
name	string	Yes	Unique name for this policy.
description	string	No	What the policy grants and when to use it.
privileges	GUID[]	Yes	IDs of the privileges to include in this policy.
condition	string	Yes	AllRequired — user must hold all privileges. AnyRequired — user must hold at least one.

A successful response returns the new policy GUID. You can then assign this policy to a role using POST /api/v1/roles/{roleId}/policies or directly to a user using POST /api/v1/users/{userId}/policies.

Best practices

Use stable names. Choose resource.action names that describe the business capability, not the UI element. invoice.approve is better than approve-button-click.

Avoid ultra-granular privileges. One privilege per screen element creates a management burden. Group related actions under a single privilege where the access boundary is the same for all of them.

Never change a privilege name after creation. Code, authorization policies, and audit logs reference the name as a stable identifier. Rename by creating a new privilege and migrating assignments.