Policy Management APIs

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

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

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

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

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
}

PDP APIs

Admin APIs

​AddOrUpdatePolicy

​HTTP Request

​Authentication

​Request Body

​Response

​Example Request

​ListPolicies

​HTTP Request

​Authentication

​Query Parameters

​Response

​Example Request

​Example Response

​InspectPolicies

​HTTP Request

​Authentication

​Query Parameters

​Response

​Example Request

​GetPolicy

​HTTP Request

​Authentication

​Query Parameters

​Response

​Example Request

​DeletePolicy

​HTTP Request

​Authentication

​Request Body

​Response

​Example Request

​Example Response

​DisablePolicy

​HTTP Request

​Authentication

​Request Body

​Response

​Example Request

​Example Response

​EnablePolicy

​HTTP Request

​Authentication

​Request Body

​Response

​Example Request

​Example Response

Build docs developers (and LLMs) love

AddOrUpdatePolicy

HTTP Request

Authentication

Request Body

Response

Example Request

ListPolicies

HTTP Request

Authentication

Query Parameters

Response

Example Request

Example Response

InspectPolicies

HTTP Request

Authentication

Query Parameters

Response

Example Request

GetPolicy

HTTP Request

Authentication

Query Parameters

Response

Example Request

DeletePolicy

HTTP Request

Authentication

Request Body

Response

Example Request

Example Response

DisablePolicy

HTTP Request

Authentication

Request Body

Response

Example Request

Example Response

EnablePolicy

HTTP Request

Authentication

Request Body

Response

Example Request

Example Response