The Cerbos Admin API :: Cerbos Authorization Management Platform // Documentation

The Cerbos Admin API

The Admin API is an optional component of the Cerbos PDP that must be enabled by setting the server.adminAPI.enabled to true in the configuration. (See Admin API configuration for details).

Authentication is mandatory for the Admin API. Currently, only basic authentication with a single admin user is supported. If no credentials are configured using the configuration, the default username and password is cerbos and cerbosAdmin.

Audit Logs

List Audit Log Entries

GET /admin/auditlog/list/{kind}

When audit logging is enabled, you can view the audit log entries using this API endpoint.

There are two kinds of audit logs:

KIND_ACCESS
- Captured Cerbos API access logs. These records are only available if accessLogsEnabled is set to true in the configuration.
KIND_DECISION
- Decision logs captured by the engine. These records are only available if decisionLogsEnabled is set to true in the configuration.

Supported filters are:

tail
- View the last N entries
between
- View entries captured between two timestamps. The time range is specified by providing two ISO-8601 timestamps using the between.start and between.end query parameters.
since
- View entries captured since N hours/minutes/seconds ago
lookup
- View a specific entry by call ID

View last 5 decision log entries

curl -k -u cerbos:cerbosAdmin \
    'https://localhost:3592/admin/auditlog/list/KIND_DECISION?tail=5'

View decision logs from 2 hours ago up to now

curl -k -u cerbos:cerbosAdmin \
    'https://localhost:3592/admin/auditlog/list/KIND_DECISION?since=2h'

View access log entries between midnight 2021-07-01 and midnight 2021-07-02

curl -k -u cerbos:cerbosAdmin \
    'https://localhost:3592/admin/auditlog/list/KIND_ACCESS?between.start=2021-07-01T00:00:00Z&between.end=2021-07-02T00:00:00Z'

View specific access log entry

curl -k -u cerbos:cerbosAdmin \
    'https://localhost:3592/admin/auditlog/list/KIND_ACCESS?lookup=01F9VS1N77S83MTSBBX44GYSJ6'

Policy Management

Add/update policies

POST /admin/policy
PUT /admin/policy

This endpoint requires a mutable storage driver such as sqlite3 to be configured.

Request

{
  "policies": [
    {
      "apiVersion": "api.cerbos.dev/v1",
      "principalPolicy": {
        "principal": "donald_duck",
        "version": "20210210",
        "rules": [
          {
            "resource": "leave_request",
            "actions": [
              {
                "action": "*",
                "condition": {
                  "match": {
                    "expr": "request.resource.attr.dev_record == true"
                  }
                },
                "effect": "EFFECT_ALLOW"
              }
            ]
          },
          {
            "resource": "salary_record",
            "actions": [
              {
                "action": "*",
                "effect": "EFFECT_DENY"
              }
            ]
          }
        ]
      }
    }
  ]
}

Response

{"success":{}}

List Policies

GET /admin/policies

Issue a GET request to the endpoint to list the policies available in the store. If the policy store supports filtering, you can optionally pass filter parameters to reduce the result set.

Use includeDisabled=true query parameter in order to include disabled policies in the response.

Use policyId query parameter to provide a list of policy IDs to be included in the result.

Use nameRegexp, scopeRegexp and versionRegexp to filter using the policy name, scope, or version with case-insensitive regular expressions.

curl -k -u cerbos:cerbosAdmin \
    'https://localhost:3592/admin/policies?pretty'

curl -k -u cerbos:cerbosAdmin \
    'https://localhost:3592/admin/policies?pretty&includeDisabled=true&nameRegexp=%5Efoo&scopeRegexp=bar%24&versionRegexp=default'

Get Policies

GET /admin/policy?id=policy_id

Issue a GET request to the endpoint with the list of IDs (the id query parameter can be repeated multiple times) to retrieve. The list of IDs available in the store can be retrieved using the ListPolicies API call described above.

curl -k -u cerbos:cerbosAdmin \
    'https://localhost:3592/admin/policy?id=x.yaml&id=y.yaml'

Inspect Policies

GET /admin/policies/inspect

Issue a GET request to the endpoint to list actions and variables covered by the policies in the store. If the policy store supports filtering, you can optionally pass filter parameters to reduce the result set.

Use includeDisabled=true query parameter in order to include disabled policies in the response.

Use policyId query parameter to provide a list of policy IDs to inspect.

Use nameRegexp, scopeRegexp and versionRegexp to filter using the policy name, scope, or version with case-insensitive regular expressions.

curl -k -u cerbos:cerbosAdmin \
    'https://localhost:3592/admin/policies/inspect'

curl -k -u cerbos:cerbosAdmin \
    'https://localhost:3592/admin/policies/inspect?policyId=x.yaml&policyId=y.yaml'

curl -k -u cerbos:cerbosAdmin \
    'https://localhost:3592/admin/policies/inspect?includeDisabled=true&nameRegexp=%5Efoo&scopeRegexp=bar%24&versionRegexp=default'

Delete Policies

POST /admin/policy/delete?id=policy_id

This endpoint requires a mutable storage driver such as sqlite3 to be configured.

Issue a POST request to the endpoint with the list of IDs (the id query parameter can be repeated multiple times) to delete.

IDs follow the same format as the output of ListPolicies (<kind>.<name>.v<version>/<scope>). For example, a resource policy for leave_request with version default and scope acme.hr would have the ID resource.leave_request.vdefault/acme.hr.

curl -k -u cerbos:cerbosAdmin -X POST \
    'https://localhost:3592/admin/policy/delete?id=principal.donald_duck.vdefault&id=derived_roles.my_derived_roles'

Response

{
  "deletedPolicies": 2
}

Disable Policies

POST /admin/policy/disable?id=policy_id
PUT /admin/policy/disable?id=policy_id
DELETE /admin/policy?id=policy_id [DEPRECATED]

This endpoint requires a mutable storage driver such as sqlite3 to be configured.

Issue a POST request to the endpoint with the list of IDs (the id query parameter can be repeated multiple times) to disable.

curl -k -u cerbos:cerbosAdmin -X POST \
    'https://localhost:3592/admin/policy/disable?id=principal.donald_duck.vdefault&id=derived_roles.my_derived_roles'

Response

{
  "disabledPolicies": 2
}

Enable Policies

POST /admin/policy/enable?id=policy_id
PUT /admin/policy/enable?id=policy_id

This endpoint requires a mutable storage driver such as sqlite3 to be configured.

Issue a POST request to the endpoint with the list of IDs (the id query parameter can be repeated multiple times) to enable.

curl -k -u cerbos:cerbosAdmin -X POST \
    'https://localhost:3592/admin/policy/enable?id=principal.donald_duck.vdefault&id=derived_roles.my_derived_roles'

Response

{
  "enabledPolicies": 2
}

Schema Management

Add/update schemas

POST /admin/schema
PUT /admin/schema

This endpoint requires a mutable storage driver such as sqlite3 to be configured.

Request

{
  "schemas": [
    {
      "id": "principal.json",
      "definition": "ewogICIkc2NoZW1hIjogImh0dHBzOi8vanNvbi1zY2hlbWEub3JnL2RyYWZ0LzIwMjAtMTIvc2NoZW1hIiwKICAidHlwZSI6ICJvYmplY3QiLAogICJwcm9wZXJ0aWVzIjogewogICAgImRlcGFydG1lbnQiOiB7CiAgICAgICJ0eXBlIjogInN0cmluZyIsCiAgICAgICJlbnVtIjogWwogICAgICAgICJtYXJrZXRpbmciLAogICAgICAgICJlbmdpbmVlcmluZyIKICAgICAgXQogICAgfSwKICAgICJnZW9ncmFwaHkiOiB7CiAgICAgICJ0eXBlIjogInN0cmluZyIKICAgIH0sCiAgICAidGVhbSI6IHsKICAgICAgInR5cGUiOiAic3RyaW5nIgogICAgfSwKICAgICJtYW5hZ2VkX2dlb2dyYXBoaWVzIjogewogICAgICAidHlwZSI6ICJzdHJpbmciCiAgICB9LAogICAgIm9yZ0lkIjogewogICAgICAidHlwZSI6ICJzdHJpbmciCiAgICB9LAogICAgImpvYlJvbGVzIjogewogICAgICAidHlwZSI6ICJhcnJheSIsCiAgICAgICJpdGVtcyI6IHsKICAgICAgICAgICJ0eXBlIjogInN0cmluZyIKICAgICAgfQogICAgfSwKICAgICJ0YWdzIjogewogICAgICAidHlwZSI6ICJvYmplY3QiLAogICAgICAicHJvcGVydGllcyI6IHsKICAgICAgICAiYnJhbmRzIjogewogICAgICAgICAgInR5cGUiOiAiYXJyYXkiLAogICAgICAgICAgIml0ZW1zIjogewogICAgICAgICAgICAgICJ0eXBlIjogInN0cmluZyIKICAgICAgICAgIH0KICAgICAgICB9LAogICAgICAgICJjbGFzc2VzIjogewogICAgICAgICAgInR5cGUiOiAiYXJyYXkiLAogICAgICAgICAgIml0ZW1zIjogewogICAgICAgICAgICAgICJ0eXBlIjogInN0cmluZyIKICAgICAgICAgIH0KICAgICAgICB9LAogICAgICAgICJyZWdpb25zIjogewogICAgICAgICAgInR5cGUiOiAiYXJyYXkiLAogICAgICAgICAgIml0ZW1zIjogewogICAgICAgICAgICAgICJ0eXBlIjogInN0cmluZyIKICAgICAgICAgIH0KICAgICAgICB9CiAgICAgIH0KICAgIH0KICB9LAogICJyZXF1aXJlZCI6IFsKICAgICJkZXBhcnRtZW50IiwKICAgICJnZW9ncmFwaHkiLAogICAgInRlYW0iCiAgXQp9Cg=="
    }
  ]
}

Response

{}

List schemas

GET /admin/schemas

Issue a GET request to the endpoint to list the schemas available in the store.

Only the schema IDs will be returned from this request. Use the GetSchema endpoint to retrieve the full definition of a schema.

curl -k -u cerbos:cerbosAdmin \
    'https://localhost:3592/admin/schemas'

Response

{
    "schemaIds": [
        "principal.json",
        "leave_request.json"
    ]
}

Get schema(s)

GET /admin/schema

Issue a GET request to the endpoint to get the schema(s) stated in the query parameters.

curl -k -u cerbos:cerbosAdmin \
    'https://localhost:3592/admin/schema?id=principal.json&id=leave_request.json'

Response

{
    "schemas": [
        {
            "id": "principal.json",
            "definition": "ewogICIkc2NoZW1hIjogImh0dHBzOi8vanNvbi1zY2hlbWEub3JnL2RyYWZ0LzIwMjAtMTIvc2NoZW1hIiwKICAidHlwZSI6ICJvYmplY3QiLAogICJwcm9wZXJ0aWVzIjogewogICAgImRlcGFydG1lbnQiOiB7CiAgICAgICJ0eXBlIjogInN0cmluZyIsCiAgICAgICJlbnVtIjogWwogICAgICAgICJtYXJrZXRpbmciLAogICAgICAgICJlbmdpbmVlcmluZyIKICAgICAgXQogICAgfSwKICAgICJnZW9ncmFwaHkiOiB7CiAgICAgICJ0eXBlIjogInN0cmluZyIKICAgIH0sCiAgICAidGVhbSI6IHsKICAgICAgInR5cGUiOiAic3RyaW5nIgogICAgfSwKICAgICJpZCI6IHsKICAgICAgInR5cGUiOiAic3RyaW5nIgogICAgfSwKICAgICJvd25lciI6IHsKICAgICAgInR5cGUiOiAic3RyaW5nIgogICAgfSwKICAgICJzdGF0dXMiOiB7CiAgICAgICJ0eXBlIjogInN0cmluZyIKICAgIH0sCiAgICAiZGV2X3JlY29yZCI6IHsKICAgICAgInR5cGUiOiAiYm9vbGVhbiIKICAgIH0KICB9LAogICJyZXF1aXJlZCI6IFsKICAgICJkZXBhcnRtZW50IiwKICAgICJnZW9ncmFwaHkiLAogICAgInRlYW0iCiAgXQp9Cg=="
        },
        {
            "id": "leave_request.json",
            "definition": "ewogICIkc2NoZW1hIjogImh0dHBzOi8vanNvbi1zY2hlbWEub3JnL2RyYWZ0LzIwMjAtMTIvc2NoZW1hIiwKICAidHlwZSI6ICJvYmplY3QiLAogICJwcm9wZXJ0aWVzIjogewogICAgImRlcGFydG1lbnQiOiB7CiAgICAgICJ0eXBlIjogInN0cmluZyIsCiAgICAgICJlbnVtIjogWwogICAgICAgICJtYXJrZXRpbmciLAogICAgICAgICJlbmdpbmVlcmluZyIKICAgICAgXQogICAgfSwKICAgICJnZW9ncmFwaHkiOiB7CiAgICAgICJ0eXBlIjogInN0cmluZyIKICAgIH0sCiAgICAidGVhbSI6IHsKICAgICAgInR5cGUiOiAic3RyaW5nIgogICAgfSwKICAgICJpZCI6IHsKICAgICAgInR5cGUiOiAic3RyaW5nIgogICAgfSwKICAgICJvd25lciI6IHsKICAgICAgInR5cGUiOiAic3RyaW5nIgogICAgfSwKICAgICJzdGF0dXMiOiB7CiAgICAgICJ0eXBlIjogInN0cmluZyIKICAgIH0sCiAgICAiZGV2X3JlY29yZCI6IHsKICAgICAgInR5cGUiOiAiYm9vbGVhbiIKICAgIH0KICB9LAogICJyZXF1aXJlZCI6IFsKICAgICJkZXBhcnRtZW50IiwKICAgICJnZW9ncmFwaHkiLAogICAgInRlYW0iLAogICAgImlkIgogIF0KfQo="
        }
    ]
}

Delete schema(s)

DELETE /admin/schema

Issue a DELETE request to the endpoint to delete the schema(s) stated in the query parameters.

curl -k -u cerbos:cerbosAdmin -X DELETE \
    'https://localhost:3592/admin/schema?id=principal.json&id=leave_request.json'

Response

{
  "deletedSchemas": 2
}

Store Management

Purge store revisions

DELETE /admin/store/revisions

Issue a DELETE request to the endpoint to delete rows from the policy_revision table.

Use keepLast=N query parameter to keep the last N revisions for each policy. If not specified, the entire table will be truncated.

Purge the store revisions

curl -k -u cerbos:cerbosAdmin -X DELETE \
    'https://localhost:3592/admin/store/revisions'

Response

{}

Reload store

GET /admin/store/reload

Issue a GET request to the endpoint to force a reload of the store.

Reload the store

curl -k -u cerbos:cerbosAdmin -X GET \
    'https://localhost:3592/admin/store/reload'

Reload the store and block until it finishes

curl -k -u cerbos:cerbosAdmin -X GET \
    'https://localhost:3592/admin/store/reload?wait=true'

Response

{}