Audit Log APIs

The Audit Log APIs allow administrators to retrieve audit log entries from the Cerbos Policy Decision Point. All endpoints require BasicAuth authentication.

ListAuditLogEntries

Retrieve audit log entries as a stream. This API supports querying both access logs (admin API calls) and decision logs (authorization checks).

HTTP Request

GET /admin/auditlog/list/{kind}

Authentication

Requires BasicAuth credentials configured in the Cerbos server.

Path Parameters

kind

string

required

Type of audit log entries to retrieve. Must be one of:

KIND_ACCESS - Admin API access logs
KIND_DECISION - Authorization decision logs

Query Parameters

Exactly one of the following filter parameters must be specified:

tail

number

Retrieve the last N entries. Minimum 1, maximum 1000.Example: tail=100

between

object

Retrieve entries within a time range.

Show TimeRange Object

start

timestamp

required

Start date in ISO 8601 format. Must be in the past.Example: 2021-07-05T07:27:01+00:00

end

timestamp

required

End date in ISO 8601 format. Must be in the past.Example: 2021-07-05T08:27:01+00:00

since

duration

Retrieve entries since N hours/minutes ago.Example: since=1h or since=30m

lookup

string

Retrieve a specific entry by its Call ID. Must be a 26-character ULID.Pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$

Response

The response is a stream of audit log entries. Each entry contains either an access log entry or a decision log entry.

entry

object

Show Entry Object

accessLogEntry

object

Access log entry for admin API calls

Show AccessLogEntry Fields

callId

string

Unique identifier for this API call

timestamp

When the call was made

peer

object

Information about the client making the request

method

string

HTTP method used

path

string

API endpoint path

statusCode

number

HTTP status code returned

decisionLogEntry

object

Decision log entry for authorization checks

Show DecisionLogEntry Fields

callId

string

Unique identifier for this authorization check

timestamp

When the check was performed

peer

object

Information about the client making the request

inputs

array

Input data for the authorization check (principal, resource, actions)

outputs

array

Authorization decisions (effects per action)

error

string

Error message if the check failed

Example Request - Last 10 Decision Logs

curl "https://cerbos.example.com/admin/auditlog/list/KIND_DECISION?tail=10" \
  -u admin:password

Example Request - Access Logs Since 1 Hour Ago

curl "https://cerbos.example.com/admin/auditlog/list/KIND_ACCESS?since=1h" \
  -u admin:password

Example Request - Logs Between Time Range

curl "https://cerbos.example.com/admin/auditlog/list/KIND_DECISION?between.start=2021-07-05T07:27:01Z&between.end=2021-07-05T08:27:01Z" \
  -u admin:password

Example Request - Lookup Specific Call

curl "https://cerbos.example.com/admin/auditlog/list/KIND_DECISION?lookup=01ARZ3NDEKTSV4RRFFQ69G5FAV" \
  -u admin:password

Example Response

{
  "decisionLogEntry": {
    "callId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "timestamp": "2021-07-05T07:27:01Z",
    "peer": {
      "address": "192.168.1.100:54321",
      "userAgent": "cerbos-sdk-go/0.1.0"
    },
    "inputs": [
      {
        "principal": {
          "id": "user123",
          "roles": ["user"]
        },
        "resource": {
          "kind": "album:object",
          "id": "album_1"
        },
        "actions": ["view", "edit"]
      }
    ],
    "outputs": [
      {
        "resourceId": "album_1",
        "actions": {
          "view": "EFFECT_ALLOW",
          "edit": "EFFECT_DENY"
        }
      }
    ]
  }
}

Use Cases

Monitoring Authorization Decisions

Use decision logs to:

Track which users are accessing which resources
Audit permission grants and denials
Identify patterns in authorization failures
Debug policy evaluation issues

Monitoring Admin Operations

Use access logs to:

Track policy changes and updates
Monitor schema modifications
Audit administrative access to the PDP
Investigate security incidents

Compliance and Reporting

Both log types support:

Time-based queries for compliance reports
Specific call ID lookups for incident investigation
Streaming for real-time monitoring
Integration with external log aggregation systems

PDP APIs

Admin APIs

Audit Log APIs

ListAuditLogEntries

HTTP Request

Authentication

Path Parameters

Query Parameters

Response

Example Request - Last 10 Decision Logs

Example Request - Access Logs Since 1 Hour Ago

Example Request - Logs Between Time Range

Example Request - Lookup Specific Call

Example Response

Use Cases

Monitoring Authorization Decisions

Monitoring Admin Operations

Compliance and Reporting

Build docs developers (and LLMs) love

PDP APIs

Admin APIs

​ListAuditLogEntries

​HTTP Request

​Authentication

​Path Parameters

​Query Parameters

​Response

​Example Request - Last 10 Decision Logs

​Example Request - Access Logs Since 1 Hour Ago

​Example Request - Logs Between Time Range

​Example Request - Lookup Specific Call

​Example Response

​Use Cases

​Monitoring Authorization Decisions

​Monitoring Admin Operations

​Compliance and Reporting

Build docs developers (and LLMs) love

ListAuditLogEntries

HTTP Request

Authentication

Path Parameters

Query Parameters

Response

Example Request - Last 10 Decision Logs

Example Request - Access Logs Since 1 Hour Ago

Example Request - Logs Between Time Range

Example Request - Lookup Specific Call

Example Response

Use Cases

Monitoring Authorization Decisions

Monitoring Admin Operations

Compliance and Reporting