Read one stored NSS account (auditor and above)

GET

/api/admin/nss/users/{uid}

curl --request GET \
  --url https://example.com/api/admin/nss/users/1 \
  --header 'X-Ssoossh-Key-Secret: <X-Ssoossh-Key-Secret>'

The posix_users row with this uid as stored, the ssoossh user linked to it, every stored membership row for the uid, and what a host’s lookup by the uid is served now, built by the lookup code itself (absent with not_served saying why when the lookup finds nothing). Reads only the database: where a host’s miss would ask the directory, this does not.

Authorizations

• sessionCookie

Parameters

Path Parameters

uid

required

integer

The account’s stored uid

Responses

200

The account

Media typeapplication/json

object

data

required

object

created_at

required

string

deleted_at

string

dir_disabled

required

DirDisabled is the directory’s own disabled flag (nss.disabled_filter).

boolean

directory_id

DirectoryID is the ldap.id_attribute value, absent when that is unset.

string

dn

DN is the entry’s DN from the last read; empty once another entry took the DN (the row is then matched by DirectoryID alone).

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”, where it is followed rather than frozen).

integer

groups

required

Groups is every stored membership row for the uid, by gid, whether or not the group is served. The primary group is not among them unless a membership row names it.

Array<object>

object

added_at

AddedAt is when ssoosshd first stored the membership, which is not the date of the add in the directory (it does not timestamp member values). Absent for a membership the first full import stored: present before that import.

string

gid

required

integer

name

Name and State describe the stored group with that gid, and are absent when no stored group has it.

string

state

string

Allowed values: withheld tombstone disabled missing pending active

home

Home and Shell are the directory’s attributes as stored, before the nss.default_home and nss.default_shell fallbacks.

string

id

required

string

last_synced_at

required

string

missing_since

string

name

required

string

not_served

string

Allowed values: withheld past_retention private_group_clash no_gid

pending_gid

integer

pending_since

string

pending_uid

integer

person

Person is the ssoossh user linked to this entry at login. Absent for shared and service accounts and for anyone who has not logged in.

object

disabled_at

string

display_name

string

user_id

required

UserID addresses the person’s admin page, /admin/users/{id}.

string

username

required

string

served

Served is what a host’s lookup by this uid gets now. Absent when the lookup finds nothing; NotServed then says why.

object

gecos

string

gid

required

GID is the primary gid after nss.auto_private_groups.

integer

groups

required

Groups is every membership served, primary first.

Array<object>

object

gid

required

integer

name

required

string

home

string

name

required

string

shell

string

status

required

string

Allowed values: active disabled deleted

uid

required

integer

shell

string

state

required

string

Allowed values: withheld tombstone disabled missing pending active

uid

required

integer

updated_at

required

string

withheld_at

string

withheld_reason

WithheldReason sums up the collisions that withhold the row.

string

error

string

Example

{
  "data": {
    "groups": [
      {
        "state": "withheld"
      }
    ],
    "not_served": "withheld",
    "served": {
      "status": "active"
    },
    "state": "withheld"
  }
}

400

The uid is not a number

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

No stored account has that uid, 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"
}