Skip to main content
POST
/
v1
/
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"

​
id
string

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

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

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

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

Example:

"plt_sk_apikey-j2k3l4_a1b2c3d4e5f6..."

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