> ## Documentation Index > Fetch the complete documentation index at: https://team.k0labs.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml api-docs/k0rdent-api.json post /v1/regions/global/iam/apikeys openapi: 3.1.0 info: title: K0rdent AI API version: 0.2.0-draft description: > OpenAPI specification for the K0rdent AI GPU-as-a-Service platform. **Custom Extensions:** - `x-visibility`: Endpoint visibility — `internal` (Atlas only), `public` (Arc only), `[internal, public]` (common) - `x-status`: Implementation status — `mvp`, `tbd`, `blocked`, `stretch` - `x-source`: Source document reference or `TBD` for fields pending confirmation **Error Model:** Standard `{ error: { code, message, details[] } }` envelope. **Pagination:** All list endpoints support two modes: - **Cursor** (`pageToken` + `pageSize`): Use for frequently updated resources. Prevents skipped or duplicated items across pages. `nextPageToken` is returned; `total` is not. - **Offset** (`offset` + `pageSize`): Use for stable resources. Returns `total` for page-count UIs. `nextPageToken` is not returned. `pageToken` and `offset` are mutually exclusive. Default `pageSize` is 50, maximum is 500. servers: - url: https://api.k0rdent.ai description: K0rdent AI API Gateway security: - bearerAuth: [] tags: - name: clusters description: Kubernetes cluster management - name: kubeconfigs description: Kubeconfig issuance and management - name: instances description: VM and baremetal instance lifecycle - name: networks description: Network configuration and topology - name: addresses description: IP address management - name: servers description: Bare metal server lifecycle management - name: organizations description: Organization (tenant) management - name: projects description: Project resource grouping - name: authentication description: Authentication and session management - name: users description: User management - name: groups description: User group management - name: roles description: RBAC role definitions - name: policies description: IAM policy bindings - name: providers description: Identity provider configuration - name: token description: > Generate access token via multiple grant types (authorization_code, api_key, client_credentials). - name: check description: > Evaluate permissions for a principal against actions and resources. Supports single and bulk checks (up to 100). - name: introspect description: > Token introspection per RFC 7662. Validate token activity and retrieve full decoded claims. - name: revoke description: > Token revocation per RFC 7009. Explicitly invalidate access tokens before natural expiration. - name: sessions description: > Manage user browser sessions. Supports listing active sessions, creating a new session (login), and ending the current session (logout). - name: apikeys description: > Manage API keys for programmatic access. API keys are bound to a user and inherit a dynamic subset of the user's privileges, evaluated at token-mint time. Keys are scoped to a level in the resource hierarchy (organization, or project). - name: serviceaccounts description: | Manage service accounts for machine-to-machine and infrastructure access. Service accounts are independent principals with their own identity, role bindings, and credentials. They survive user off-boarding and are managed exclusively by tenant administrators. paths: /v1/regions/global/iam/apikeys: post: tags: - apikeys summary: Create API key description: > **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. operationId: createApiKey requestBody: required: true content: application/json: schema: type: object required: - displayName - scope - scopeId properties: id: type: string description: | Client-provided resource identifier. If omitted, the server generates one. Must match [a-z]([-a-z0-9]*[a-z0-9])?. pattern: ^[a-z]([-a-z0-9]*[a-z0-9])?$ minLength: 1 maxLength: 63 displayName: type: string description: Human-readable display name. minLength: 1 maxLength: 255 example: CI/CD Pipeline Key description: type: string description: Optional description of the key's intended use. maxLength: 1024 scope: type: string enum: - organization - project description: | The hierarchy level this key is scoped to. Subject to org-level policy (e.g., org may prohibit org-scoped keys). example: project scopeId: type: string description: | 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 roles: type: array items: type: string description: | 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: type: string format: date-time description: | Requested expiration timestamp. Cannot exceed the org-level maximum key lifetime. Defaults to org default if omitted. responses: '201': description: API key created. Secret is included in this response only. content: application/json: schema: type: object description: | Full API key metadata plus the secret value. The secret is only returned at creation and rotation time. allOf: - $ref: '#/components/schemas/ApiKey' - type: object required: - secret properties: secret: type: string description: | Opaque, prefixed API key secret. Store securely — this value cannot be retrieved again. example: plt_sk_apikey-j2k3l4_a1b2c3d4e5f6... '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': description: | Validation error. Common causes: expiresAt exceeds org maximum, role slug not recognized, or role not held by the caller. content: application/json: schema: $ref: '#/components/schemas/Error' '500': $ref: '#/components/responses/InternalServerError' components: schemas: ApiKey: type: object description: | 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. required: - id - uid - displayName - scope - scopeId - status - createdAt - createdBy properties: selfLink: type: string format: uri description: Server-defined URL for this resource. readOnly: true example: /v1/iam/api-keys/apikey-j2k3l4 uid: type: string format: uuid description: Server-generated UUID. Immutable. readOnly: true id: type: string description: | Resource identifier. Provided by the client at creation or server-generated if omitted. Must be 1-63 lowercase characters matching [a-z]([-a-z0-9]*[a-z0-9])?. Immutable after creation. pattern: ^[a-z]([-a-z0-9]*[a-z0-9])?$ minLength: 1 maxLength: 63 example: apikey-j2k3l4 displayName: type: string description: Human-readable display name for the API key. minLength: 1 maxLength: 255 example: CI/CD Pipeline Key description: type: string description: Optional description of the key's intended use. maxLength: 1024 scope: type: string enum: - organization - project description: | 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). example: project scopeId: type: string description: | 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 roles: type: array items: type: string description: | 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 status: type: string enum: - active - disabled - expired description: | 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. readOnly: true example: active expiresAt: type: string format: date-time description: | Key expiration timestamp. If not set at creation, defaults to the organization's configured maximum API key lifetime. Cannot exceed the org-level maximum. createdBy: type: string description: | User ID of the principal who created this key. The key's privilege ceiling is derived from this user. readOnly: true example: user-xyz789 createdAt: type: string format: date-time description: Timestamp when the key was created. readOnly: true updatedAt: type: string format: date-time description: Timestamp of the last metadata change (name, roles, status). readOnly: true lastRotatedAt: type: string format: date-time description: Timestamp of the most recent secret rotation. Null if never rotated. readOnly: true lastUsedAt: type: string format: date-time description: Timestamp of the last successful token mint using this key. readOnly: true lastUsedIp: type: string description: IP address from which the key was last used. readOnly: true example: 203.0.113.42 Error: type: object description: Standard error response properties: error: type: object properties: code: type: integer description: HTTP status code message: type: string description: Error message details: type: array items: type: object description: Additional error details responses: BadRequest: description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' Conflict: description: | The request conflicts with the current state of a resource. Common causes include attempting to create a resource with an identifier that already exists, or performing a state transition that is not permitted (e.g., re-enabling an expired API key, rotating a disabled key). content: application/json: schema: $ref: '#/components/schemas/Error' examples: duplicateId: summary: Resource ID already exists value: code: CONFLICT message: A resource with id 'my-deploy-key' already exists. invalidStateTransition: summary: Invalid state transition value: code: CONFLICT message: Cannot rotate a disabled API key. Re-enable it first. InternalServerError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: Bearer token authentication using OAuth2/OIDC tokens ````