Create a fleet API key

POST

/api/nss/keys

curl --request POST \
  --url https://example.com/api/nss/keys \
  --header 'Content-Type: application/json' \
  --header 'X-Ssoossh-Key-Secret: <X-Ssoossh-Key-Secret>' \
  --data '{}'

Fleet key admin role and admins only. Returns the key and its secret; the secret is shown this once and never again, so the caller must store it now. expires_at defaults to nss.key_max_lifetime from now, and a later one is trimmed to that; with the setting at 0 a key created without one never expires. Afterwards only a rotation renews it. notification_email defaults to the creator’s address.

Authorizations

• sessionCookie

Request Body^required

The new key

Media typeapplication/json

One of:

object

object

object

The new key

object

description

string

expires_at

string

group_name

string

name

required

string

notification_email

string

Example ^generated

{}

Responses

200

The key and its secret

Media typeapplication/json

object

data

required

object

key

required

object

created_at

required

string

created_by

required

CreatedBy is the creator’s users.id, and CreatedByUsername their username, empty when the account is gone.

string

created_by_username

required

string

current_generation

required

CurrentGeneration is 1 at creation and grows by one per rotation.

integer

description

required

string

expires_at

ExpiresAt is when the key stops being accepted, set at creation and renewed by each rotation; absent for a key that never expires.

string

group_name

required

GroupName is the group whose members manage this key, empty for none.

string

id

required

ID is “nss_” and 8 base32 characters, what hosts send as X-Ssoossh-Key-Id. Fixed for the key’s life.

string

key_source_alert_at

KeySourceAlertAt is when the key source alert (nss.key_source_alert) last fired for the key: more source addresses in one day than the limit. Absent unless it fired in the last 7 days.

string

last_used_at

LastUsedAt is the last lookup any host made with the key, from the retained usage, so up to a minute behind; absent for a key no host has used.

string

miss_rate_alert_at

MissRateAlertAt is when the miss rate alert (nss.miss_alert_rate) last fired for the key: many lookups for names the directory does not hold. Absent unless it fired in the last 7 days.

string

name

required

string

notification_email

required

NotificationEmail is where the key’s mail goes, empty for nowhere.

string

permissions

required

Permissions is what the caller may do with this key, decided by the server so the UI never reimplements the role matrix. A revoked key carries view alone.

Array<string>

Allowed values: view rotate revoke edit assign_group

previous_expires_at

PreviousExpiresAt is when the previous secret stops being accepted, absent when there is no previous secret.

string

revoked_at

RevokedAt, RevokedBy (a users.id) and RevokedByUsername record a revocation, absent while the key is live.

string

revoked_by

string

revoked_by_username

string

rotated_at

RotatedAt is the last rotation, absent for a key never rotated.

string

status

required

Status is derived from the revocation and expiry.

string

Allowed values: active expired revoked

updated_at

required

string

secret

required

string

error

string

Example

{
  "data": {
    "key": {
      "permissions": [
        "view"
      ],
      "status": "active"
    }
  }
}

400

Malformed body, a missing name, a past expiry or a bad address

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

No valid session

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 the fleet key admin role, or no user record

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

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