End a fleet API key's previous secret early

DELETE

/api/nss/keys/{id}/previous

curl --request DELETE \
  --url https://example.com/api/nss/keys/example/previous \
  --header 'X-Ssoossh-Key-Secret: <X-Ssoossh-Key-Secret>'

Stops accepting the previous secret before its rotation grace ends, once every host has switched. Who may rotate the key may do this. A key with no previous secret is a 409.

Authorizations

• sessionCookie

Parameters

Path Parameters

id

required

string

Key id

Responses

200

The key after the change

Media typeapplication/json

object

data

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

error

string

Example

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

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

The caller may view the key but not rotate it

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 such key the caller may view, or nss_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"
}

409

The key is revoked or has no previous secret

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