Skip to content
ssoossh

Look a POSIX user up by name

GET
/api/nss/user/name/{name}
curl --request GET \
  --url https://example.com/api/nss/user/name/example

Resolves a login name, matched byte for byte, to the account a host serves: uid, primary gid (after nss.auto_private_groups), every group with its name, home, shell, gecos and a status derived on read. A disabled or deleted account is served with nss.disabled_shell. Called by ssoossh-nss with a fleet key. 404 nss_not_found is the one answer a host may cache as a miss.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
name
required
string

The login name, by the relaxed POSIX rules nss-systemd applies

Responses

Section titled “Responses”

200

Section titled “200”

The account

Media typeapplication/json
object
data
required
object
gecos

Gecos is the rendered and sanitised nss.gecos_template output.

string
gid

GID is the primary group id, after nss.auto_private_groups.

integer
groups
required

Groups is every membership, primary first, with the gid and the name together, so one user lookup answers both “which groups” and “what is group N called”.

Array<object>
object
gid

GID is the group id.

integer
name
required

Name is the group name, matched byte for byte like a user name.

string
home

Home is the home directory: the directory attribute, else nss.default_home expanded, else null.

string
key_id
required

KeyID is the fleet key that made the request, echoed for log correlation.

string
name
required

Name is the login name, stored verbatim from the directory and matched byte for byte.

string
shell

Shell is the login shell path: the directory attribute, else nss.default_shell, else null. For a disabled or deleted account it is nss.disabled_shell.

string
status
required

Status is one of the NSSStatus* values.

string
uid

UID is the user id. Frozen once stored: a changed directory value is held as a pending change until an admin accepts it.

integer
error
string

Example generated

{
  "data": {
    "gecos": "example",
    "gid": 1,
    "groups": [
      {
        "gid": 1,
        "name": "example"
      }
    ],
    "home": "example",
    "key_id": "example",
    "name": "example",
    "shell": "example",
    "status": "example",
    "uid": 1
  },
  "error": "example"
}

400

Section titled “400”

Nss_bad_request: the name fails validation

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”

Nss_unauthorized: the fleet key is missing, unknown, revoked, expired or wrong

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”

Nss_forbidden: the source address is outside nss.source_allow_list

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”

Nss_not_found, or nss_disabled when nss.enabled is false

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

429

Section titled “429”

Nss_rate_limited, with Retry-After

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

503

Section titled “503”

Unavailable: the name is not in the database and the directory could not be asked

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