Skip to main content
PATCH
/
v1
/
regions
/
global
/
iam
/
apikeys
/
{id}
Update API key
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({displayName: '<string>', description: '<string>', roles: ['<string>']})
};

fetch('https://api.k0rdent.ai/v1/regions/global/iam/apikeys/{id}', 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",
  "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
​
displayName
string

Updated display name.

Required string length: 1 - 255
​
description
string

Updated description.

Maximum string length: 1024
​
roles
string[]

Updated privilege ceiling for the key. Each role must be a valid org-defined role slug currently held by the caller within the key's scope. Effective privileges are evaluated at token-mint time as the intersection of this list and the creating user's current roles within the key's scope boundary.

Pass an empty array to remove the ceiling entirely, allowing the key to mirror the creating user's full privileges within the key's scope boundary.

​
status
enum<string>

Toggle key status. Only active ↔ disabled transitions are permitted. Expired keys cannot be modified.

Available options:
active,
disabled

Response

Updated API key metadata.

API key for programmatic access. Keys are scoped to a level in the resource hierarchy (organization, or project) and inherit a subset of the creating user's privileges, evaluated dynamically at token-mint time. The key secret is an opaque, prefixed token shown only at creation and rotation time.

​
uid
string<uuid>
required
read-only

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 [blocked]?. 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
read-only

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
read-only

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
read-only

Timestamp when the key was created.

​
selfLink
string<uri>
read-only

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>
read-only

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

​
lastRotatedAt
string<date-time>
read-only

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

​
lastUsedAt
string<date-time>
read-only

Timestamp of the last successful token mint using this key.

​
lastUsedIp
string
read-only

IP address from which the key was last used.

Example:

"203.0.113.42"