Skip to content
ssoossh

Look a POSIX group up by name

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

Resolves a group name, matched byte for byte, to its gid and member names, capped at nss.max_group_members with members_truncated set when the cap applies. An account’s private group under nss.auto_private_groups resolves too, with no members. A tombstoned group resolves with no members. Called by ssoossh-nss with a fleet key.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
name
required
string

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

Responses

Section titled “Responses”

200

Section titled “200”

The group

Media typeapplication/json
object
data
required
object
gid

GID is the group id, frozen once stored like NSSUserResponse.UID.

integer
members
required

Members are the member user names, capped at nss.max_group_members.

Array<string>
members_truncated

MembersTruncated is true when the cap cut Members short, so a host can log that the list is incomplete rather than serve it as whole.

boolean
name
required

Name is the group name.

string
error
string

Example generated

{
  "data": {
    "gid": 1,
    "members": [
      "example"
    ],
    "members_truncated": true,
    "name": "example"
  },
  "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"
}