Skip to content
ssoossh

View a user's audit timeline (auditor-only)

GET
/api/admin/users/{id}/audit
curl --request GET \
  --url 'https://example.com/api/admin/users/example/audit?limit=25' \
  --header 'X-Ssoossh-Key-Secret: <X-Ssoossh-Key-Secret>'

Returns the audit events where this user is the actor or the target, newest first. One row serves both sides: a disable shows on the analyst’s history and on the disabled account’s page. Uses cursor-based pagination (not offset).

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string

User ID

Query Parameters

Section titled “Query Parameters”
after
string

Audit event ID to start after (cursor): the previous page’s next_cursor; must be on this user’s timeline

limit
integer

Page size (default 25, max 100)

Example 

25

Responses

Section titled “Responses”

200

Section titled “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

Section titled “400”

Invalid paging parameters, an after that names no event on this timeline, or offset

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

Section titled “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

Section titled “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"
}