Skip to content
ssoossh

View a stored NSS group's audit history (auditor and above)

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

The audit events about the posix_groups row with this gid, newest first: its lifecycle (created, renamed, missing, tombstoned, revived, purged), every change to its members, its collisions, and pending and accepted gid changes. The history belongs to the row, so it follows a rename or an accepted gid change. Uses cursor-based pagination (not offset), as /api/admin/users/{id}/audit does.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
gid
required
integer

The group’s stored gid

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 group’s history

limit
integer

Page size (default 25, max 100)

Example 

25

Responses

Section titled “Responses”

200

Section titled “200”

Audit events

Media typeapplication/json
object
data
required
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
error
string

Example generated

{
  "data": {
    "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
  },
  "error": "example"
}

400

Section titled “400”

The gid is not a number, invalid paging parameters, an after that names no event on this history, 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"
}

404

Section titled “404”

No stored group has that gid, or NSS is disabled

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"
}