---
title: "Update Api Key"
method: PATCH
path: "/v1/organizations/users/{user_email}/api-keys/{key_name}"
tags: ["Organization API Keys"]
---

# Update Api Key

`PATCH /v1/organizations/users/{user_email}/api-keys/{key_name}`

Update an API key's metadata or permissions.

🔒 The "admin-key" is protected and cannot be modified.

## Path parameters

- `user_email` string, required
- `key_name` string, required

## Request body

- APIKeyUpdateRequest — Partial update payload for an API key.
  - `name` string, nullable — New key label.
  - `description` string, nullable — Updated description for the key.
  - `permissions` Permission[], nullable — Replace existing permissions with the provided list.
  - `scopes` ResourceScopeInput[], nullable — Replace existing scopes. Use empty list for global access.
    - `resource_type` 'organization' | 'user' | 'api_key' | 'namespace' | 'collection' | 'document' | 'bucket' | 'retriever' | 'cluster' | 'taxonomy' | 'storage_connection' | 'alert' | 'annotation' | 'secret' | 'webhook', required — Resource surfaces supported by scoped API keys and audit events. These resource types can be used in: - API key scopes to restrict access to specific resources - Audit logs to identify what type of resource was affected - Permission systems to grant/deny access to resource categories Resource hierarchy: ORGANIZATION -> USER, API_KEY, STORAGE_CONNECTION NAMESPACE -> COLLECTION, BUCKET, RETRIEVER, CLUSTER, TAXONOMY Resource types: - ORGANIZATION: Top-level tenant entity - USER: Organization member with authentication credentials - API_KEY: Authentication token for programmatic access - NAMESPACE: Isolated environment for data and compute resources - COLLECTION: Vector database collection for searchable documents - DOCUMENT: A single searchable document within a collection - BUCKET: Object storage container for raw files - RETRIEVER: Configured search/retrieval pipeline - CLUSTER: Ray compute cluster for distributed processing - TAXONOMY: Hierarchical classification system for documents - STORAGE_CONNECTION: External storage provider integration
    - `resource_id` string, required — Identifier or pattern for the resource. Accepts a literal ID (e.g. 'ns_production') or wildcard forms such as '*' or 'ns_customer_*'.
    - `operations` NamespaceOperation[], nullable — Subset of operations allowed within the scope. When omitted the key may perform any operation permitted by its Permission list.
  - `rate_limit_override` integer, nullable — Updated per-key rate limit override.
  - `expires_at` string, date-time, nullable — New expiration timestamp. Use null to remove expiration.
  - `status` 'active' | 'revoked' | 'expired' — Lifecycle state of an API key. Status determines whether an API key can be used for authentication: - ACTIVE: Key is valid and can be used for API requests. Last_used_at timestamp is updated on each successful authentication. - REVOKED: Key has been manually revoked by an admin or user. Cannot be reactivated. A new key must be created instead. - EXPIRED: Key has passed its expires_at timestamp. Automatically set by the authentication system. Cannot be reactivated.
  - `allowed_origins` string[], nullable — Replace the key's allowed HTTP origins. Supports exact matches and wildcard subdomains (e.g., 'https://*.example.com'). Use an empty list to remove the origin restriction.

## Response `200`

Successful Response

- APIKeyModel — API key document stored in MongoDB.
  - `key_id` string — Public identifier for the API key.
  - `key_hash` string, required — SHA-256 hash of the plaintext key.
  - `key_prefix` string, nullable — Visible prefix of the API key for user identification (e.g., 'sk_abc123...'). Shows the first 10 characters of the plaintext key to help users identify which key is which in lists, without exposing the full secret. This follows industry best practices from GitHub, Stripe, and AWS. Generated automatically for new keys. Older keys may not have this field.
  - `key_type` 'standard' | 'marketplace_subscription' | 'retriever' | 'user_scoped' | 'session' — Type of API key determining its purpose and scope. - STANDARD: Regular organization API key with standard permissions. - MARKETPLACE_SUBSCRIPTION: Special key generated for marketplace subscriptions, allowing cross-org access to specific marketplace retrievers. - RETRIEVER: Per-retriever API key scoped to execute a specific retriever. Only the retriever owner can create these keys. Prefix: ret_sk_ - SESSION: Short-lived key minted by Studio on each login to back the authenticated UI. Hidden from the user-facing key list endpoints.
  - `subscription_id` string, nullable — Marketplace subscription ID if this is a marketplace subscription key. Only set when key_type is MARKETPLACE_SUBSCRIPTION.
  - `is_internal` boolean — SERVER-VERIFIED internal-actor marker. When True, this key belongs to Mixpeek's own operations (e.g. the in-org ops/health probe that must authenticate under a dedicated tenant's internal_id because the single-tenant pod gate fail-closes cross-org auth) and its usage is NOT billed to the org: accrue_mvs_usage skips the accrual and consume_credits skips the direct charge. FAIL CLOSED — absent/False means BILL. This is the ONLY server-side source a billing skip may key on; never the client-influenced X-Mixpeek-Traffic header or mixpeek-loop-* User-Agent. Set only by an admin provisioning an internal key, never from a create request.
  - `internal_id` string, required — Organization internal identifier.
  - `organization_id` string, nullable — Organization public identifier (denormalized).
  - `user_id` string, required — Identifier of the user who owns the key.
  - `name` string, required — Human-friendly key label.
  - `description` string — Optional description explaining the key usage.
  - `permissions` Permission[] — Permissions granted to the key.
  - `scopes` ResourceScopeOutput[] — Resource-level scopes restricting the key.
    - `resource_type` 'organization' | 'user' | 'api_key' | 'namespace' | 'collection' | 'document' | 'bucket' | 'retriever' | 'cluster' | 'taxonomy' | 'storage_connection' | 'alert' | 'annotation' | 'secret' | 'webhook', required — Resource surfaces supported by scoped API keys and audit events. These resource types can be used in: - API key scopes to restrict access to specific resources - Audit logs to identify what type of resource was affected - Permission systems to grant/deny access to resource categories Resource hierarchy: ORGANIZATION -> USER, API_KEY, STORAGE_CONNECTION NAMESPACE -> COLLECTION, BUCKET, RETRIEVER, CLUSTER, TAXONOMY Resource types: - ORGANIZATION: Top-level tenant entity - USER: Organization member with authentication credentials - API_KEY: Authentication token for programmatic access - NAMESPACE: Isolated environment for data and compute resources - COLLECTION: Vector database collection for searchable documents - DOCUMENT: A single searchable document within a collection - BUCKET: Object storage container for raw files - RETRIEVER: Configured search/retrieval pipeline - CLUSTER: Ray compute cluster for distributed processing - TAXONOMY: Hierarchical classification system for documents - STORAGE_CONNECTION: External storage provider integration
    - `resource_id` string, required — Identifier or pattern for the resource. Accepts a literal ID (e.g. 'ns_production') or wildcard forms such as '*' or 'ns_customer_*'.
    - `operations` NamespaceOperation[], nullable — Subset of operations allowed within the scope. When omitted the key may perform any operation permitted by its Permission list.
  - `rate_limit_override` integer, nullable — Optional per-key rate limit override in requests per minute.
  - `status` 'active' | 'revoked' | 'expired' — Lifecycle state of an API key. Status determines whether an API key can be used for authentication: - ACTIVE: Key is valid and can be used for API requests. Last_used_at timestamp is updated on each successful authentication. - REVOKED: Key has been manually revoked by an admin or user. Cannot be reactivated. A new key must be created instead. - EXPIRED: Key has passed its expires_at timestamp. Automatically set by the authentication system. Cannot be reactivated.
  - `expires_at` string, date-time, nullable — UTC timestamp when the key automatically expires.
  - `last_used_at` string, date-time, nullable — UTC timestamp of the last successful request using the key.
  - `created_at` string, date-time — UTC timestamp when the key was created.
  - `created_by` string, nullable — User identifier that created the key.
  - `revoked_at` string, date-time, nullable — UTC timestamp when the key was revoked (if applicable).
  - `revoked_by` string, nullable — User identifier that revoked the key (if applicable).
  - `allowed_origins` string[], nullable — Optional list of allowed HTTP origins for this API key. When set, requests must include an Origin header matching one of these values. Supports exact matches (e.g., 'https://docs.example.com') and wildcard subdomains (e.g., 'https://*.example.com'). Only enforced for browser requests (defense-in-depth, not a security boundary). Null means no origin restriction.
  - `principal_id` string, nullable — End-user identifier for document-level ACL (row-level security). When set, this key is user-scoped: all document reads are automatically filtered to documents the principal owns or has been granted access to. This represents an end-user in your application, NOT an org user.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

## Changes

- **2026-08-09** `5d4c905106b4` — 1 info
  - the endpoint scheme security `BearerAuth` was added to the API
- **2026-08-05** `fdb4bdd01a64` — 1 warning, 1 info
  - added the new `document` enum value to the `scopes/items/resource_type` response property for the response status `200`
  - added the new `document` enum value to the request property `scopes/anyOf[subschema #1]/items/resource_type`

[Change history](https://skmtc.dev/mixpeek/apis/mixpeek-api/changes/v1/organizations/users/:user_email/api-keys/:key_name/patch.md)

---

[API](https://skmtc.dev/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.dev/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/revisions/0c7a1c6ab9c0/schema)