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

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.

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

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'

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 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 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'

Get Policies

GET /admin/policy?id=policy_id

Disable Policies

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

Issue a POST request to the endpoint with the list of IDs (the id query parameter can be repeated multiple times) to disable. The ID is of the form <kind>.<name>.v<version>/<scope>. A resource policy for leave_request with version default and scope acme.hr would therefore have the ID resource.leave_request.vdefault/acme.hr.

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

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

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.

Response

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

Get schema(s)

GET /admin/schema

Response

{
    "schemas": [
        {
            "id": "principal.json",
            "definition": "ewogICIkc2NoZW1hIjogImh0dHBzOi8vanNvbi1zY2hlbWEub3JnL2RyYWZ0LzIwMjAtMTIvc2NoZW1hIiwKICAidHlwZSI6ICJvYmplY3QiLAogICJwcm9wZXJ0aWVzIjogewogICAgImRlcGFydG1lbnQiOiB7CiAgICAgICJ0eXBlIjogInN0cmluZyIsCiAgICAgICJlbnVtIjogWwogICAgICAgICJtYXJrZXRpbmciLAogICAgICAgICJlbmdpbmVlcmluZyIKICAgICAgXQogICAgfSwKICAgICJnZW9ncmFwaHkiOiB7CiAgICAgICJ0eXBlIjogInN0cmluZyIKICAgIH0sCiAgICAidGVhbSI6IHsKICAgICAgInR5cGUiOiAic3RyaW5nIgogICAgfSwKICAgICJpZCI6IHsKICAgICAgInR5cGUiOiAic3RyaW5nIgogICAgfSwKICAgICJvd25lciI6IHsKICAgICAgInR5cGUiOiAic3RyaW5nIgogICAgfSwKICAgICJzdGF0dXMiOiB7CiAgICAgICJ0eXBlIjogInN0cmluZyIKICAgIH0sCiAgICAiZGV2X3JlY29yZCI6IHsKICAgICAgInR5cGUiOiAiYm9vbGVhbiIKICAgIH0KICB9LAogICJyZXF1aXJlZCI6IFsKICAgICJkZXBhcnRtZW50IiwKICAgICJnZW9ncmFwaHkiLAogICAgInRlYW0iLAogICAgImlkIgogIF0KfQo="
        },
        {
            "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.

Response

{
  "deletedSchemas": 2
}

Store Management

Reload store

GET /admin/store/reload

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

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

Response

{}