Sign in

v5

latestOpenAPI 3.1.02026-08-025631,1012.8 MB
Retriever API Keys

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

Path parameters

retriever_idstring required

Request body

namestring required

Human-friendly key label for identification.

descriptionstring nullable

Optional description explaining the key's purpose.

expires_atstring date-time nullable

Optional UTC timestamp when the key automatically expires.

allowed_originsstring[] nullable

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 request

{
  "description": "Production API key for external service",
  "expires_at": "2026-12-31T23:59:59Z",
  "name": "production-key"
}

Response

Successful Response

key_idstring

Public identifier for the API key.

key_hashstring required

SHA-256 hash of the plaintext key.

key_prefixstring 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_idstring nullable

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

is_internalboolean

SERVER-VERIFIED internal-actor marker (BACKE-2564). 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_idstring required

Organization internal identifier.

organization_idstring nullable

Organization public identifier (denormalized).

user_idstring required

Identifier of the user who owns the key.

namestring required

Human-friendly key label.

descriptionstring

Optional description explaining the key usage.

permissionsPermission[]

Permissions granted to the key.

rate_limit_overrideinteger 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_atstring date-time nullable

UTC timestamp when the key automatically expires.

last_used_atstring date-time nullable

UTC timestamp of the last successful request using the key.

created_atstring date-time

UTC timestamp when the key was created.

created_bystring nullable

User identifier that created the key.

revoked_atstring date-time nullable

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

revoked_bystring nullable

User identifier that revoked the key (if applicable).

allowed_originsstring[] 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_idstring 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.

keystring required

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

Example response

{
  "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"
}