Create Retriever API Key

Generate a scoped API key for executing this specific retriever.

Use Cases:

• Provide external services with execution-only access
• Embed retriever calls in customer applications
• Create separate keys for staging vs production
• Implement per-customer access keys for SaaS products

Security:

• Keys grant EXECUTE_RETRIEVER permission only
• Keys are scoped to single retriever (cannot access others)
• Keys inherit org’s rate limits
• Keys can be revoked instantly
• Key prefix (ret_sk_abc…) shown in UI for identification

Ownership:

• Only the organization that owns the retriever can create keys
• Verified by matching internal_id + namespace_id

Key Format:

• Prefix: ret_sk_
• Length: 60 characters
• Example: ret_sk_abcdefghijklmnopqrstuvwxyz123456789…

Response:

• Plaintext key shown ONLY ONCE in response
• Save the key immediately - it cannot be retrieved later
• Key prefix stored for identification in UI

POST /v1/retrievers/{retriever_id}/api-keys

Create Retriever API Key

cURL

curl --request POST \
  --url https://api.mixpeek.com/v1/retrievers/{retriever_id}/api-keys \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <api-key>' \
  --data '
{
  "description": "Production API key for external service",
  "expires_at": "2026-12-31T23:59:59Z",
  "name": "production-key"
}
'

200

{
  "created_at": "2025-01-01T00:00:00Z",
  "created_by": "usr_admin",
  "description": "Service account for ingestion",
  "internal_id": "int_x1y2z3",
  "key_hash": "2c26b46b68ffc68ff99b453c1d304134",
  "key_id": "key_a1b2c3d4e5f6g7h",
  "key_prefix": "sk_abc123...",
  "name": "backend-service",
  "organization_id": "org_demo123",
  "permissions": [
    "read",
    "write"
  ],
  "scopes": [],
  "status": "active",
  "user_id": "usr_a1b2c3d4e5f6g7h"
}

Authorizations

Authorization · string · header · required

Mixpeek API key, sent as Authorization: Bearer mxp_sk_.... Create one in Studio under Settings → API Keys, or with an admin key via POST /v1/organizations/users/{user_email}/api-keys. A missing, malformed, unknown, revoked, inactive or expired key returns 401; a key without the permission, scope or plan an operation needs returns 403.

X-Namespace · string · header · required

Namespace id (ns_...), not the namespace name. This scopes the request rather than authenticating it, and it is required on every operation marked x-mixpeek-namespace-scoped.

Path Parameters

retriever_id · string · required

Body

application/json

Keys this body does not declare are refused with 422 extra_forbidden naming the accepted keys (since 2026-11-02).

Request payload for creating a retriever-scoped API key.

Retriever keys are automatically scoped to execute a specific retriever. The scope and permissions are auto-populated by the service layer and cannot be modified.

Example: { "name": "production-api", "description": "Production API key for customer integrations", "expires_at": "2026-12-31T23:59:59Z" }

name · string · required

Human-friendly key label for identification.

Required string length: 1 - 100

description · string | null

Optional description explaining the key's purpose.

Maximum string length: 500

expires_at · string<date-time> | null

Optional UTC timestamp when the key automatically expires.

allowed_origins · string[] | null

Optional list of allowed HTTP origins for this API key. When set, browser requests must include a matching Origin header. Supports exact matches and wildcard subdomains (e.g., 'https://*.example.com'). Defense-in-depth: Origin headers can be spoofed from non-browser contexts.

Example:

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

Response

200

application/json

Successful Response

Response model including the plaintext key (shown only once).

This response is returned immediately after key creation. The plaintext key is shown ONLY in this response and cannot be retrieved later. Users should save the key immediately for secure storage.

Security note: The key field contains the plaintext secret and should be: - Stored securely by the user (environment variables, secrets manager) - Never committed to version control - Never logged or exposed in error messages - Rotated/revoked if accidentally exposed

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

Plaintext API key (shown only once). Prefix: ret_sk_. Store securely immediately after creation.

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.

Maximum string length: 64

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, workload

subscription_id · string | null

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

is_internal · boolean · default: false

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.

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.