Read one stored NSS group (auditor and above)

GET

/api/admin/nss/groups/{gid}

const url = 'https://example.com/api/admin/nss/groups/1';
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/groups/1 \
  --header 'X-Ssoossh-Key-Secret: <X-Ssoossh-Key-Secret>'

The posix_groups row with this gid as stored, its count of stored membership rows, and what a host’s lookup by the gid is served now, built by the lookup code itself, with the member names counted after nss.max_group_members (absent with not_served saying why when the lookup finds nothing). The members are paged from /api/admin/nss/groups/{gid}/members. Reads only the database: where a host’s miss would ask the directory, this does not.

Authorizations

sessionCookie

Parameters

Path Parameters

gid

required

integer

The group’s stored gid

Responses

200

The group

application/json

object

data

required

object

created_at

required

string

deleted_at

string

directory_id

string

gid

required

integer

required

string

last_synced_at

required

string

member_count

required

MemberCount is the stored membership rows, served or not.

integer

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

served

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

object

gid

required

integer

member_count

required

MemberCount is how many member names the host receives, after nss.max_group_members.

integer

members_truncated

required

MembersTruncated is true when nss.max_group_members cut the list.

boolean

name

required

string

state

required

string

Allowed values: withheld tombstone disabled missing pending active

updated_at

required

string

withheld_at

string

withheld_reason

WithheldReason sums up the collisions that withhold the row.

string

error

string

Example

{
  "data": {
    "not_served": "withheld",
    "state": "withheld"
  }
}

400

The gid is not a number

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

No stored group has that gid, or 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"
}