> ## 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. # Update API key > **Visibility:** `public` · `internal` ( OpenAPI Custom Extension: x-visibility ) Update mutable fields on an API key. Supports changing the display name, description, roles (scope-down only — cannot exceed the creating user's privileges), and toggling the status between active and disabled. Regular users can only update keys they created. Requests targeting keys owned by other users return 404 to prevent key ID enumeration. Tenant administrators can update any key within the tenant. Expired keys cannot be re-enabled. To restore access, create a new key. ## OpenAPI ````yaml api-docs/k0rdent-api.json patch /v1/regions/global/iam/apikeys/{id} 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/{id}: parameters: - name: id in: path required: true description: API key resource identifier. schema: type: string patch: tags: - apikeys summary: Update API key description: > **Visibility:** `public` · `internal` ( OpenAPI Custom Extension: x-visibility ) Update mutable fields on an API key. Supports changing the display name, description, roles (scope-down only — cannot exceed the creating user's privileges), and toggling the status between active and disabled. Regular users can only update keys they created. Requests targeting keys owned by other users return 404 to prevent key ID enumeration. Tenant administrators can update any key within the tenant. Expired keys cannot be re-enabled. To restore access, create a new key. operationId: updateApiKey requestBody: required: true content: application/json: schema: type: object minProperties: 1 properties: displayName: type: string description: Updated display name. minLength: 1 maxLength: 255 description: type: string description: Updated description. maxLength: 1024 roles: type: array items: type: string description: | 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: type: string enum: - active - disabled description: | Toggle key status. Only active ↔ disabled transitions are permitted. Expired keys cannot be modified. responses: '200': description: Updated API key metadata. content: application/json: schema: $ref: '#/components/schemas/ApiKey' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': description: | Validation error. Role slug not recognized, or role exceeds the creating user's current privileges. 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' NotFound: description: Not found 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 ````