Revoke a fleet API key

POST

/api/nss/keys/{id}/revoke

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

Ends the key for good: neither secret is accepted again. The fleet key admin role, admins, SOC, or the key’s group. Already revoked is a 409.

Authorizations

• sessionCookie

Parameters

Path Parameters

id

required

string

Key id

Responses

200

The revoked key

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 revoke 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 already revoked

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