Rotate Api Key

Rotate an API key and return the new secret.

🔒 The “admin-key” is protected and cannot be rotated.

POST /v1/organizations/users/{user_email}/api-keys/{key_name}/rotate

Rotate Api Key

cURL

curl --request POST \
  --url https://api.mixpeek.com/v1/organizations/users/{user_email}/api-keys/{key_name}/rotate

200

{
  "key_hash": "<string>",
  "internal_id": "<string>",
  "user_id": "<string>",
  "name": "<string>",
  "key": "<string>",
  "key_id": "<string>",
  "key_prefix": "sk_abc123...",
  "key_type": "standard",
  "subscription_id": "<string>",
  "organization_id": "<string>",
  "description": "",
  "permissions": [
    "read"
  ],
  "scopes": [
    {
      "resource_type": "organization",
      "resource_id": "<string>",
      "operations": [
        "read_data"
      ]
    }
  ],
  "rate_limit_override": 123,
  "status": "active",
  "expires_at": "2023-11-07T05:31:56Z",
  "last_used_at": "2023-11-07T05:31:56Z",
  "created_at": "2023-11-07T05:31:56Z",
  "created_by": "<string>",
  "revoked_at": "2023-11-07T05:31:56Z",
  "revoked_by": "<string>",
  "allowed_origins": [
    "https://docs.example.com",
    "https://*.example.com"
  ],
  "principal_id": "<string>"
}

Headers

Authorization · string

REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.

Examples:

"Bearer YOUR_API_KEY"

"Bearer YOUR_STRIPE_API_KEY"

Path Parameters

user_email · string · required

key_name · string · required

Response

200

application/json

Successful Response

API key response including the plaintext secret.

key_hash · string · required

SHA-256 hash of the plaintext key.

internal_id · string · required

Organization internal identifier.

user_id · string · required

Identifier of the user who owns the key.

name · string · required

Human-friendly key label.

key · string · required

key_id · string

Public identifier for the API key.

key_prefix · string | null

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.

Required string length: 10 - 13

Example:

"sk_abc123..."

key_type · enum<string> · default: standard

Type of API key. STANDARD for regular organization keys, MARKETPLACE_SUBSCRIPTION for marketplace subscription access tokens.

Available options: standard, marketplace_subscription, retriever, user_scoped, session

subscription_id · string | null

Marketplace subscription ID if this is a marketplace subscription key. Only set when key_type is MARKETPLACE_SUBSCRIPTION.

organization_id · string | null

Organization public identifier (denormalized).

description · string · default: ""

Optional description explaining the key usage.

permissions · enum<string>[]

Permissions granted to the key.

Simplified API key permissions.

This four-value enum replaces the legacy 16-permission model. Keep usage simple: prefer the least privileged option that satisfies the workflow.

Hierarchy (strongest -> weakest): ADMIN > DELETE > WRITE > READ.

Available options: read, write, delete, admin

scopes · ResourceScope · object[]

Resource-level scopes restricting the key.

Show child attributes

rate_limit_override · integer | null

Optional per-key rate limit override in requests per minute.

status · enum<string> · default: active

Lifecycle status of the key (active, revoked, expired).

Available options: active, revoked, expired

expires_at · string<date-time> | null

UTC timestamp when the key automatically expires.

last_used_at · string<date-time> | null

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 | null

User identifier that created the key.

revoked_at · string<date-time> | null

UTC timestamp when the key was revoked (if applicable).

revoked_by · string | null

User identifier that revoked the key (if applicable).

allowed_origins · string[] | null

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.

Example:

[
  "https://docs.example.com",
  "https://*.example.com"
]

principal_id · string | null

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.