Skip to main content
POST
/
v1
/
regions
/
global
/
iam
/
apikeys
/
{id}
:rotate
Rotate API key secret
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({gracePeriodSeconds: 120})
};

fetch('https://api.k0rdent.ai/v1/regions/global/iam/apikeys/{id}:rotate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "uid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "id": "apikey-j2k3l4",
  "displayName": "CI/CD Pipeline Key",
  "scope": "project",
  "scopeId": "proj-abc123",
  "status": "active",
  "createdBy": "user-xyz789",
  "createdAt": "2023-11-07T05:31:56Z",
  "secret": "plt_sk_apikey-j2k3l4_x9y8z7w6v5u4...",
  "previousSecretExpiresAt": "2023-11-07T05:31:56Z",
  "selfLink": "/v1/iam/api-keys/apikey-j2k3l4",
  "description": "<string>",
  "roles": [
    "viewer",
    "member"
  ],
  "expiresAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "lastRotatedAt": "2023-11-07T05:31:56Z",
  "lastUsedAt": "2023-11-07T05:31:56Z",
  "lastUsedIp": "203.0.113.42"
}

Authorizations

​
Authorization
string
header
required

Bearer token authentication using OAuth2/OIDC tokens

Path Parameters

​
id
string
required

API key resource identifier.

Body

application/json
​
gracePeriodSeconds
integer
default:0

Duration in seconds during which both the old and new secrets are valid. Allows distributed systems to pick up the new secret without downtime.

Required range: 0 <= x <= 300
Example:

120

Response

Key rotated successfully. The new secret is included in this response only and cannot be retrieved again.

API key metadata with the new secret value.

​
uid
string<uuid>
required

Server-generated UUID. Immutable.

​
id
string
required

Resource identifier. Provided by the client at creation or server-generated if omitted. Must be 1-63 lowercase characters matching a-z?. Immutable after creation.

Required string length: 1 - 63
Pattern: ^[a-z]([-a-z0-9]*[a-z0-9])?$
Example:

"apikey-j2k3l4"

​
displayName
string
required

Human-readable display name for the API key.

Required string length: 1 - 255
Example:

"CI/CD Pipeline Key"

​
scope
enum<string>
required

The level in the resource hierarchy this key is scoped to. Determines the resource boundary for all operations performed with this key:

  • organization: key can access all projects the creating user has access to within the tenant.
  • project: key is restricted to a single project.

Combined with scopeId, this defines the key's blast radius. Subject to org-level policy constraints (e.g., an org may prohibit organization-scoped keys).

Available options:
organization,
project
Example:

"project"

​
scopeId
string
required

Resource identifier corresponding to the scope level:

  • organization scope: the organization ID (derived from the caller's tenant — must match the caller's org).
  • project scope: a project ID the caller has access to.
Example:

"proj-abc123"

​
status
enum<string>
required

Current key status.

  • active: Key can be used to mint tokens.
  • disabled: Temporarily suspended. Can be re-enabled via PATCH.
  • expired: Past expiresAt. Terminal; cannot be re-enabled.
Available options:
active,
disabled,
expired
Example:

"active"

​
createdBy
string
required

User ID of the principal who created this key. The key's privilege ceiling is derived from this user.

Example:

"user-xyz789"

​
createdAt
string<date-time>
required

Timestamp when the key was created.

​
secret
string
required

New opaque, prefixed API key secret. Store securely — cannot be retrieved again.

Example:

"plt_sk_apikey-j2k3l4_x9y8z7w6v5u4..."

​
previousSecretExpiresAt
string<date-time>
required

Timestamp when the previous secret becomes invalid. Equal to the current time when gracePeriodSeconds is 0. Null if no previous secret existed.

​
selfLink
string<uri>

Server-defined URL for this resource.

Example:

"/v1/iam/api-keys/apikey-j2k3l4"

​
description
string

Optional description of the key's intended use.

Maximum string length: 1024
​
roles
string[]

Optional role bindings that act as a privilege ceiling for the key. Effective privileges are evaluated at token-mint time, not at key creation time:

  • When roles are set: effective privilege is the intersection of this list and the creating user's current roles for the key's project. If the user gains or loses roles, the key's effective privilege adjusts automatically.
  • When empty or omitted: the key mirrors the creating user's full current roles for the project, expanding and shrinking as the user's roles change.

Each role must be a valid org-defined role slug. At creation and update time, every listed role must be held by the caller; however, the key remains valid if the user later loses a listed role (it simply has no effect until the user regains it).

Effective privileges are always bounded by the key's scope (organization, or project).

Example:
["viewer", "member"]
​
expiresAt
string<date-time>

Key expiration timestamp. If not set at creation, defaults to the organization's configured maximum API key lifetime. Cannot exceed the org-level maximum.

​
updatedAt
string<date-time>

Timestamp of the last metadata change (name, roles, status).

​
lastRotatedAt
string<date-time>

Timestamp of the most recent secret rotation. Null if never rotated.

​
lastUsedAt
string<date-time>

Timestamp of the last successful token mint using this key.

​
lastUsedIp
string

IP address from which the key was last used.

Example:

"203.0.113.42"