List the stored NSS accounts (auditor and above)

GET

/api/admin/nss/users

const url = 'https://example.com/api/admin/nss/users?limit=25&q=ada&state=withheld';
const options = {method: 'GET', headers: {'X-Ssoossh-Key-Secret': '<X-Ssoossh-Key-Secret>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

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

One page of the posix_users rows, ordered by name then id, each with its derived state. q matches a case-insensitive substring of the name or DN, and also the exact uid 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

string

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

Example

ada

state

string

Allowed values: withheld tombstone disabled missing pending active

State filter; omitted returns every state

Responses

200

One page of accounts

application/json

object

data

required

object

accounts

required

Array<object>

object

required

string

gecos

string

gid

GID is the stored gid attribute, before nss.auto_private_groups; absent when the entry has none (accepted only under “true”).

integer

required

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

string

last_synced_at

required

LastSyncedAt is the last sync or on-demand read that reached the directory for this entry.

string

name

required

string

state

required

string

Allowed values: withheld tombstone disabled missing pending active

uid

required

integer

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 accounts match the search, across all pages.

integer

error

string

Example

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

400

Invalid paging/search parameters, an unknown state, an after that names no account, or offset

application/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

application/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

application/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

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