Policy Management APIs

Admin APIs for managing Cerbos policies including adding, updating, listing, retrieving, deleting, disabling, and enabling policies.

The Policy Management APIs allow administrators to manage policies in the Cerbos Policy Decision Point. All endpoints require BasicAuth authentication.

AddOrUpdatePolicy

Add or update one or more policies in the policy store.

HTTP Request

POST /admin/policy
PUT /admin/policy

Authentication

Requires BasicAuth credentials configured in the Cerbos server.

Request Body

policies · array · required

Array of policy objects to add or update. Minimum 1, maximum 100 policies.

Show Policy Object

apiVersion · string · required

API version, must be “api.cerbos.dev/v1”

disabled · boolean

Whether the policy is disabled

description · string

Description of the policy

metadata · object

Policy metadata including annotations and source information

resourcePolicy · object

Resource policy definition (one of resourcePolicy, principalPolicy, or derivedRoles must be specified)

Show ResourcePolicy Fields

resource · string · required

Resource type identifier

version · string · required

Policy version

rules · array

Array of resource rules

scope · string

Dot-separated scope hierarchy

principalPolicy · object

Principal policy definition

derivedRoles · object

Derived roles definition

Response

success · object

Empty object indicating successful operation

Example Request

curl -X POST https://cerbos.example.com/admin/policy \
  -u admin:password \
  -H "Content-Type: application/json" \
  -d '{
    "policies": [
      {
        "apiVersion": "api.cerbos.dev/v1",
        "resourcePolicy": {
          "resource": "album:object",
          "version": "default",
          "rules": [
            {
              "actions": ["view", "edit"],
              "effect": "EFFECT_ALLOW",
              "roles": ["owner"]
            }
          ]
        }
      }
    ]
  }'

---

ListPolicies

List all policy IDs stored in the Cerbos server with optional filtering.

HTTP Request

GET /admin/policies

Authentication

Requires BasicAuth credentials configured in the Cerbos server.

Query Parameters

includeDisabled · boolean

Include disabled policies in the results

nameRegexp · string

Filter policies by name using a regular expression

scopeRegexp · string

Filter policies by scope using a regular expression

versionRegexp · string

Filter policies by version using a regular expression

policyId · array

Filter by specific policy IDs. Maximum 25 IDs. For file-based stores (blob, disk, git), use filename with extension. For database stores (mysql, postgres, sqlite3), use the format kind.name.version.

Example: principal.sarah.vdefault

Response

policyIds · array

Array of policy ID strings

Example Request

curl https://cerbos.example.com/admin/policies?includeDisabled=true \
  -u admin:password

Example Response

{
  "policyIds": [
    "principal.sarah.vdefault",
    "resource.album.vdefault",
    "derived_roles.common_roles"
  ]
}

---

InspectPolicies

Inspect policies to see detailed information including which policies would be evaluated for a given request.

HTTP Request

GET /admin/policies/inspect

Authentication

Requires BasicAuth credentials configured in the Cerbos server.

Query Parameters

principal · string

Principal ID to inspect policies for

resource · string

Resource kind to inspect policies for

action · string

Action to inspect policies for

includeDisabled · boolean

Include disabled policies in the results

Response

results · array

Array of inspection results showing which policies would apply

Show Inspection Result

policyId · string

ID of the policy

scope · string

Scope of the policy

actions · array

Actions defined in the policy

variables · object

Variables defined in the policy

Example Request

curl "https://cerbos.example.com/admin/policies/inspect?principal=user123&resource=album:object&action=view" \
  -u admin:password

---

GetPolicy

Retrieve one or more policies by their IDs.

HTTP Request

GET /admin/policy

Authentication

Requires BasicAuth credentials configured in the Cerbos server.

Query Parameters

id · array · required

One or more policy IDs to retrieve. Minimum 1 ID required. For file-based stores (blob, disk, git), use filename with extension. For database stores (mysql, postgres, sqlite3), use the format kind.name.version.

Example: principal.sarah.vdefault

Response

policies · array

Array of policy objects matching the requested IDs

Show Policy Object

apiVersion · string

API version

disabled · boolean

Whether the policy is disabled

description · string

Policy description

metadata · object

Policy metadata

resourcePolicy · object

Resource policy definition (if applicable)

principalPolicy · object

Principal policy definition (if applicable)

derivedRoles · object

Derived roles definition (if applicable)

Example Request

curl "https://cerbos.example.com/admin/policy?id=principal.sarah.vdefault" \
  -u admin:password

---

DeletePolicy

Permanently delete one or more policies from the policy store.

HTTP Request

POST /admin/policy/delete

Authentication

Requires BasicAuth credentials configured in the Cerbos server.

Request Body

id · array · required

Array of policy IDs to delete. Minimum 1, maximum 20 IDs. For file-based stores (blob, disk, git), use filename with extension. For database stores (mysql, postgres, sqlite3), use the format kind.name.version.

Example: principal.sarah.vdefault

Response

deletedPolicies · number

Number of policies successfully deleted

Example Request

curl -X POST https://cerbos.example.com/admin/policy/delete \
  -u admin:password \
  -H "Content-Type: application/json" \
  -d '{
    "id": ["principal.sarah.vdefault"]
  }'

Example Response

{
  "deletedPolicies": 1
}

---

DisablePolicy

Disable one or more policies without deleting them. Disabled policies are not evaluated during authorization checks.

HTTP Request

POST /admin/policy/disable
PUT /admin/policy/disable
DELETE /admin/policy

Authentication

Requires BasicAuth credentials configured in the Cerbos server.

Request Body

id · array · required

Array of policy IDs to disable. Minimum 1, maximum 20 IDs. For file-based stores (blob, disk, git), use filename with extension. For database stores (mysql, postgres, sqlite3), use the format kind.name.version.

Example: principal.sarah.vdefault

Response

disabledPolicies · number

Number of policies successfully disabled

Example Request

curl -X POST https://cerbos.example.com/admin/policy/disable \
  -u admin:password \
  -H "Content-Type: application/json" \
  -d '{
    "id": ["principal.sarah.vdefault"]
  }'

Example Response

{
  "disabledPolicies": 1
}

---

EnablePolicy

Re-enable one or more previously disabled policies.

HTTP Request

POST /admin/policy/enable
PUT /admin/policy/enable

Authentication

Requires BasicAuth credentials configured in the Cerbos server.

Request Body

id · array · required

Array of policy IDs to enable. Minimum 1 ID required. For file-based stores (blob, disk, git), use filename with extension. For database stores (mysql, postgres, sqlite3), use the format kind.name.version.

Example: principal.sarah.vdefault

Response

enabledPolicies · number

Number of policies successfully enabled

Example Request

curl -X POST https://cerbos.example.com/admin/policy/enable \
  -u admin:password \
  -H "Content-Type: application/json" \
  -d '{
    "id": ["principal.sarah.vdefault"]
  }'

Example Response

{
  "enabledPolicies": 1
}