List the stored NSS groups (auditor and above)

GET

/api/admin/nss/groups

curl --request GET \
  --url 'https://example.com/api/admin/nss/groups?limit=25&q=engineering&state=withheld' \
  --header 'X-Ssoossh-Key-Secret: <X-Ssoossh-Key-Secret>'

One page of the posix_groups rows, ordered by name then id, each with its derived state and its count of stored membership rows. Private groups are never stored, so are not listed. q matches a case-insensitive substring of the name or DN, and also the exact gid when it is a number. Uses cursor-based pagination (not offset): pass the previous page’s next_cursor as after. Reads only the database: never the directory, and never writes.

Authorizations

• sessionCookie

Parameters

Query Parameters

after

string

Row id to start after (cursor): the previous page’s next_cursor

limit

integer

Page size (default 25, max 100)

Example

25

q

string

Search term matched against name and DN, or an exact gid

Example

engineering

state

string

Allowed values: withheld tombstone missing pending active

State filter; omitted returns every state

Responses

200

One page of groups

Media typeapplication/json

object

data

required

object

groups

required

Array<object>

object

dn

required

string

gid

required

integer

id

required

ID is the row id, the list’s cursor. The group’s own pages are addressed by GID.

string

last_synced_at

required

string

member_count

required

MemberCount is the stored membership rows, served or not.

integer

name

required

string

state

required

string

Allowed values: withheld tombstone disabled missing pending active

next_cursor

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

string

total

required

Total is how many stored groups match the search, across all pages.

integer

error

string

Example

{
  "data": {
    "groups": [
      {
        "state": "withheld"
      }
    ]
  }
}

400

Invalid paging/search parameters, an unknown state, an after that names no group, 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

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

404

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