View the recent audit event feed (auditor-only)

GET

/api/admin/audit

curl --request GET \
  --url 'https://example.com/api/admin/audit?limit=25&action=cert.request_refused_network&source_ip=192.0.2.10' \
  --header 'X-Ssoossh-Key-Secret: <X-Ssoossh-Key-Secret>'

Returns the administrative audit stream newest first, optionally filtered to one action, one source address, or both. Both filters are exact matches. The source address is the one the server observed for the client the event is about (detail.source_ip), never the approver’s address and never one the client reported. The database copy is a bounded cache of recent events; the shipped audit log is the archive, and any other search happens there. Uses cursor-based pagination (not offset): pass the previous page’s next_cursor as after.

Authorizations

• sessionCookie

Parameters

Query Parameters

after

string

Audit event ID to start after (cursor): the previous page’s next_cursor

limit

integer

Page size (default 25, max 100)

Example

25

action

string

Only events of this audit action; must be in the taxonomy

Example

cert.request_refused_network

source_ip

string

Only events whose observed source is this IP address

Example

192.0.2.10

Responses

200

Audit events

Media typeapplication/json

object

events

required

Array<object>

object

action

required

Action is the namespaced action name, e.g. “user.disabled”. The set grows without a wire change, so a client must render an unknown action rather than assume the list is closed.

string

actor

object

email

string

groups

Array<string>

subject

string

user_id

UserID is the grouping key the timelines are built on. It may be empty (a system or anonymous actor) and it may no longer match any row, which does not make the rest of the snapshot less true.

string

username

string

created_at

required

string

detail

Detail is the per-action specifics, passed through as decoded JSON so a new action’s fields reach the UI without a wire type change. Never carries a secret.

object

key

additional properties

id

required

string

reason

string

system

System marks an action taken by the server rather than a person, which is how a reader tells “nobody” from “not recorded”.

boolean

target

object

email

string

groups

Array<string>

subject

string

user_id

UserID is the grouping key the timelines are built on. It may be empty (a system or anonymous actor) and it may no longer match any row, which does not make the rest of the snapshot less true.

string

username

string

next_cursor

NextCursor is the after for the following page: the id of this page’s last event, absent on the last page.

string

total

integer

Example ^generated

{
  "events": [
    {
      "action": "example",
      "actor": {
        "email": "example",
        "groups": [
          "example"
        ],
        "subject": "example",
        "user_id": "example",
        "username": "example"
      },
      "created_at": "example",
      "detail": {
        "additionalProperty": "example"
      },
      "id": "example",
      "reason": "example",
      "system": true,
      "target": {
        "email": "example",
        "groups": [
          "example"
        ],
        "subject": "example",
        "user_id": "example",
        "username": "example"
      }
    }
  ],
  "next_cursor": "example",
  "total": 1
}

400

Invalid paging parameters, an after that names no audit event, offset, an unknown action, or a source_ip that is not an IP address

Media typeapplication/json

object

data

Data is always null on an error response.

error

required

Error is a human-readable message. Branch on the HTTP status rather than this string; it is for humans and logs.

string

error_code

required

ErrorCode is a machine-readable error classifier. One of the error_code constants from internal/apitypes; use this to decide whether to retry or branch on the failure mode.

string

Example

{
  "error": "certificate request \"9f1c…\" not found",
  "error_code": "not_found"
}

401

Not authenticated

Media typeapplication/json

object

data

Data is always null on an error response.

error

required

Error is a human-readable message. Branch on the HTTP status rather than this string; it is for humans and logs.

string

error_code

required

ErrorCode is a machine-readable error classifier. One of the error_code constants from internal/apitypes; use this to decide whether to retry or branch on the failure mode.

string

Example

{
  "error": "certificate request \"9f1c…\" not found",
  "error_code": "not_found"
}

403

Not authorized as auditor

Media typeapplication/json

object

data

Data is always null on an error response.

error

required

Error is a human-readable message. Branch on the HTTP status rather than this string; it is for humans and logs.

string

error_code

required

ErrorCode is a machine-readable error classifier. One of the error_code constants from internal/apitypes; use this to decide whether to retry or branch on the failure mode.

string

Example

{
  "error": "certificate request \"9f1c…\" not found",
  "error_code": "not_found"
}