Create API key

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    displayName: 'CI/CD Pipeline Key',
    scope: 'project',
    scopeId: 'proj-abc123',
    id: '<string>',
    description: '<string>',
    roles: ['viewer', 'member'],
    expiresAt: '2023-11-07T05:31:56Z'
  })
};

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

apikeys

Create API key

Visibility: public · internal ( OpenAPI Custom Extension: x-visibility )

Generate a new API key scoped to a level in the resource hierarchy (organization, or project). The key’s effective privileges are evaluated dynamically at token-mint time — they are always the intersection of the key’s role list (if set) and the creating user’s current roles within the key’s scope boundary. This means the key automatically reflects role changes on the parent user: if the user gains or loses roles, the key’s effective access adjusts accordingly. Disabling or deleting the parent user effectively neutralizes all their keys.

The scope level may be constrained by org-level policy (e.g., an organization may prohibit organization-scoped keys to enforce least-privilege).

The secret value is returned only in this response and cannot be retrieved again. Store it securely.

If expiresAt is omitted, the organization’s default API key lifetime is applied. The value cannot exceed the org-level maximum.

POST

regions

global

iam

apikeys

Create API key

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    displayName: 'CI/CD Pipeline Key',
    scope: 'project',
    scopeId: 'proj-abc123',
    id: '<string>',
    description: '<string>',
    roles: ['viewer', 'member'],
    expiresAt: '2023-11-07T05:31:56Z'
  })
};

fetch('https://api.k0rdent.ai/v1/regions/global/iam/apikeys', 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_a1b2c3d4e5f6...",
  "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

Body

application/json

displayName

string

required

Human-readable display name.

Required string length: 1 - 255

Example:

"CI/CD Pipeline Key"

scope

enum<string>

required

The hierarchy level this key is scoped to. Subject to org-level policy (e.g., org may prohibit org-scoped keys).

Available options:

organization,

project

Example:

"project"

scopeId

string

required

Resource identifier for the scope target. Must be a resource the caller has access to:

organization: the caller's org ID.
project: a project ID.

Example:

"proj-abc123"

string

Client-provided resource identifier. If omitted, the server generates one. Must match a-z [blocked]?.

Required string length: 1 - 63

Pattern: ^[a-z]([-a-z0-9]*[a-z0-9])?$

description

string

Optional description of the key's intended use.

Maximum string length: 1024

roles

string[]

Optional roles to scope down the key's privileges. Each must be a valid org-defined role slug the caller holds. If omitted, inherits the caller's full privileges within the key's scope boundary.

Example:

["viewer", "member"]

expiresAt

string<date-time>

Requested expiration timestamp. Cannot exceed the org-level maximum key lifetime. Defaults to org default if omitted.

Response

API key created. Secret is included in this response only.

Full API key metadata plus the secret value. The secret is only returned at creation and rotation time.

uid

string<uuid>

required

read-only

Server-generated UUID. Immutable.

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.

secret

string

required

Opaque, prefixed API key secret. Store securely — this value cannot be retrieved again.

Example:

"plt_sk_apikey-j2k3l4_a1b2c3d4e5f6..."

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"

List API keys

Retrieve API key details