Security & Tenancy

Mixpeek enforces organization-level authentication, namespace isolation, and stage-level validation across the entire stack. This page summarizes the security model and operational protections you should configure in production.

Authentication

Header: Authorization: Bearer <api_key>
API keys belong to an organization; keys can be rotated, revoked, or scoped per environment.
Sensitive operations (e.g., creating namespaces, rotating keys) require elevated permissions.

See API Keys for the full lifecycle: creating keys, setting read/write/delete/admin permissions and resource scopes, rotating and revoking, per-key rate limits, usage attribution, and end-user (principal_id) keys.

Namespace Isolation

Header: X-Namespace: <namespace_id or namespace_name>
Every MongoDB query filters on namespace_id; indexes ensure isolation at scale.
MVS uses one namespace per namespace (ns_<namespace_id>); payload filters ensure cross-namespace safety.
Redis cache keys and Ray job metadata include namespace identifiers.

Dual Identifier Model

Identifier	Visible?	Purpose
`organization_id`	Yes	User-facing identifier in API responses
`internal_id`	No	Primary key for service-to-service lookups
`namespace_id`	Yes	Isolation boundary for data and compute

Keep internal_id secret; it is intentionally absent from public APIs.

Authorization & Rate Limits

Routes declare required permission levels (read, write, delete, admin).
Rate limits enforced via Redis middleware; set per-plan and per-route to protect backends.
Tasks and retriever executions are metered in dollars; analytics endpoints expose usage metrics for billing reconciliation.

Secrets & Credentials

Mixpeek provides an encrypted secrets vault for storing sensitive credentials like API keys. Secrets are encrypted at rest using Fernet symmetric encryption and are never exposed in API responses.

Organization Secrets Vault

Store and manage secrets via the API:

curl -X POST "https://api.mixpeek.com/v1/organizations/secrets" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "secret_name": "openai_api_key",
    "secret_value": "sk-proj-abc123..."
  }'

# Returns secret names only - values are never exposed
curl "https://api.mixpeek.com/v1/organizations/secrets" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X PUT "https://api.mixpeek.com/v1/organizations/secrets/openai_api_key" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "secret_value": "sk-proj-new-key..."
  }'

curl -X DELETE "https://api.mixpeek.com/v1/organizations/secrets/openai_api_key" \
  -H "Authorization: Bearer YOUR_API_KEY"

Bring Your Own Key (BYOK)

Use your own LLM API keys instead of Mixpeek’s default keys. This gives you:

Benefit	Description
Cost Control	Use your own LLM provider account and billing
Rate Limits	Use your own rate limits instead of shared
Compliance	Keep API calls under your own account
Key Rotation	Rotate keys without modifying retrievers

Supported Providers

Provider	Secret Name Example	Models
OpenAI	`openai_api_key`	gpt-4o, gpt-4o-mini
Anthropic	`anthropic_api_key`	claude-3-haiku, claude-3-sonnet, claude-3-opus
Google	`google_api_key`	gemini-3.1-flash-lite, gemini-2.5-pro

Apply a Key to All LLM Operations

The fastest way to use your own key is to set it as the organization-wide default. Once configured, it automatically applies to every LLM operation — extractors, retrievers, clustering, taxonomy inference, and manifest generation — with no per-stage configuration needed.

Store your key in the secrets vault

curl -X POST "https://api.mixpeek.com/v1/organizations/secrets" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "secret_name": "openai_api_key",
    "secret_value": "sk-proj-abc123..."
  }'

from mixpeek import Mixpeek

mx = Mixpeek(api_key="YOUR_API_KEY")
mx.organizations.secrets.create(
    secret_name="openai_api_key",
    secret_value="sk-proj-abc123..."
)

Set it as the org-wide default for that provider

curl -X PATCH "https://api.mixpeek.com/v1/organizations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "default_llm_credentials": {
      "openai": "openai_api_key"
    }
  }'

mx.organizations.update(
    default_llm_credentials={
        "openai": "openai_api_key"
    }
)

You can configure defaults for multiple providers at once:

{
  "default_llm_credentials": {
    "openai": "my_openai_key",
    "anthropic": "my_anthropic_key",
    "google": "my_gemini_key"
  }
}

You can also do this from Studio: when creating a secret, toggle “Use as default LLM key” and it will automatically be applied org-wide for the detected provider.

Values in default_llm_credentials are secret names (not raw API keys). The actual keys are stored encrypted in your secrets vault and resolved at runtime.

Override a Key on a Specific Stage

If you need a different key for a particular retriever stage, extractor, or cluster config, set api_key directly using the {{secrets.name}} template syntax. This overrides the org-wide default for that operation only.

{
  "stages": [
    {
      "stage_name": "llm_enrich",
      "stage_type": "enrich",
      "config": {
        "stage_id": "llm_enrich",
        "parameters": {
          "provider": "openai",
          "model": "gpt-4o-mini",
          "prompt": "Summarize this document.",
          "output_field": "summary",
          "api_key": "{{secrets.openai_api_key}}"
        }
      }
    }
  ]
}

Credential Resolution Order

Mixpeek resolves LLM credentials in this order (highest priority first):

Per-resource api_key / {{secrets.name}} — explicit key on a specific stage or extractor
Organization default — set once via default_llm_credentials, applied everywhere
Mixpeek platform keys — used when no custom key is configured (usage charged to your Mixpeek account)

Security

Encryption at rest: All secrets are encrypted using Fernet symmetric encryption with a dedicated encryption key
Zero exposure: Secret values are never returned in API responses — only secret names are visible
Per-request resolution: Credentials are decrypted on-demand for each LLM call, not cached globally
No cross-tenant leakage: Each organization’s credentials are isolated; provider instances with custom keys are never shared between organizations
Audit trail: Secret access and organization configuration changes are logged for compliance

Security Best Practices

Rotate credentials regularly – Update secrets via the API without changing retriever configurations
Use IAM roles – For S3/GCS access, prefer IAM roles over long-lived access keys
Audit access logs – Monitor secret access patterns for anomalies
Scope API keys – Issue environment-specific Mixpeek API keys (dev, staging, prod)

Audit Trail

Every audited write records who changed what, and optionally why. Read the trail with GET /v1/organizations/audit/logs (filter by resource_id), one entry with GET /v1/organizations/audit/logs/{audit_id}, or the whole thing as NDJSON via GET /v1/organizations/audit/logs/export.

Everything on this page arrived in one release, so confirm it against the host you call before depending on it. Deployments move backward as well as forward: a rollback returns a whole release at once, so a capability that answered yesterday can stop answering without anything failing.The cheapest check is a write. Send a change with X-Change-Reason, read the audit entry back, and look at reason and at the shape of changes. A populated reason and {old, new} values mean the release is present. An absent reason means it is not, and nothing will have told you.

Record why, not just what

Send X-Change-Reason on any audited write and the reason comes back on the audit event.

curl -X PATCH "$MP_API_URL/v1/retrievers/$RETRIEVER_ID" \
  -H "Authorization: Bearer $MP_API_KEY" \
  -H "X-Change-Reason: widening recall for the Q3 catalogue refresh" \
  -H "Content-Type: application/json" \
  -d '{ "description": "..." }'

The header is captured for the whole request, so it applies to every audited write the call performs. The value is trimmed, has control characters stripped, and is capped at 1,000 characters. An explicit reason= passed by an endpoint that takes one wins over the header. On a deployment that predates this, the header is ignored rather than rejected: the write succeeds and reason comes back empty. That is the check in the note above, and it is the only signal you get.

X-Change-Reason is not in the OpenAPI spec. It is read request-wide rather than declared per operation, so it appears on no endpoint’s parameter list and the generated API reference cannot show it. This page is where it is documented.You can still confirm it is working: the reason field on AuditEventResponse names it, and a write sent with the header comes back with reason populated.

Reading `changes`

changes is a JSON object, and datetime values inside it are ISO 8601 strings.

{
  "audit_id": "aud_...",
  "resource_type": "retriever",
  "action": "update",
  "reason": "widening recall for the Q3 catalogue refresh",
  "changes": {
    "description": { "old": "...", "new": "..." },
    "updated_at": { "old": "2026-08-01T09:00:00Z", "new": "2026-08-23T16:04:11Z" }
  }
}

How much detail changes carries depends on the resource:

Resource	`changes` contains
Retriever, namespace, cluster, taxonomy	Value-level `{field: {old, new}}`
Collection common PATCH, bucket updates	Value-level, once BACKE-3494 reaches your deployment
Alerts update	Changed field names only
Object and document updates	Changed field names only
Collection `feature_extractor` repair path	Changed field names only

Names-only is not a bug, and value-level parity is still rolling out. Where the table says names-only, changes tells you which fields moved and not what they moved from or to.Value-level diffs for collection and bucket updates landed on main on 2026-08-23 and ride the normal deploy. Verify against a real entry before building a compliance report on the shape: patch a collection, read the audit entry, and check whether its changes values are {old, new} objects or bare field names.Repeat that check a few times during a rollout. A deploy replaces servers gradually, so for a while some carry a change and others do not, and one request tells you only which server answered. Two identical writes minutes apart can land on different sides. Treat a capability as live once repeated checks agree, not on the first success.Check the host you actually call. A dedicated tenant deployment rolls separately from the shared API, so the answer differs by host rather than by date. All three changes here reached the shared API before any of them reached at least one tenant deployment.

Data Protection

Storage: rely on encryption at rest provided by MongoDB Atlas, MVS, or your infrastructure.
Transit: require TLS for API endpoints and Ray Serve; use mTLS or network policies for cross-service traffic when available.
Backups: configure automated backups for MongoDB and MVS; version S3 buckets with lifecycle policies.

Operational Safeguards

Enable /v1/health probes in load balancers to route around unhealthy instances.
Use webhooks to detect ingestion completion; failed webhook deliveries remain retriable in MongoDB.
Monitor rate-limit counters and task failure rates to spot abusive or buggy clients.
Log request IDs and namespace IDs to correlate incidents quickly.

Hardening Checklist

Network – restrict API access to trusted origins, configure CORS, and use private networking for backend services.
Auth – issue scoped API keys, expire unused keys, enable audit logging.
Secrets – manage via Vault, AWS Secrets Manager, GCP Secret Manager, or Kubernetes secrets with rotation.
Tenancy – adopt one namespace per environment/tenant; enforce X-Namespace always.
Monitoring – alert on health endpoint status, rate-limit breaches, or repeated 401/403 responses.

Get started

Connect your data

Extract features

Build retrievers

Enrich & organize

Integrate & operate

Resources

Security & Tenancy

Authentication

Namespace Isolation

Dual Identifier Model

Authorization & Rate Limits

Secrets & Credentials

Organization Secrets Vault

Bring Your Own Key (BYOK)

Supported Providers

Apply a Key to All LLM Operations

Override a Key on a Specific Stage

Credential Resolution Order

Security

Security Best Practices

Audit Trail

Record why, not just what

Reading `changes`

Data Protection

Operational Safeguards

Hardening Checklist

References

​Authentication

​Namespace Isolation

​Dual Identifier Model

​Authorization & Rate Limits

​Secrets & Credentials

​Organization Secrets Vault

​Bring Your Own Key (BYOK)

​Supported Providers

​Apply a Key to All LLM Operations

​Override a Key on a Specific Stage

​Credential Resolution Order

​Security

​Security Best Practices

​Audit Trail

​Record why, not just what

​Reading changes

​Data Protection

​Operational Safeguards

​Hardening Checklist

​References

Authentication

Namespace Isolation

Dual Identifier Model

Authorization & Rate Limits

Secrets & Credentials

Organization Secrets Vault

Bring Your Own Key (BYOK)

Supported Providers

Apply a Key to All LLM Operations

Override a Key on a Specific Stage

Credential Resolution Order

Security

Security Best Practices

Audit Trail

Record why, not just what

Reading `changes`

Data Protection

Operational Safeguards

Hardening Checklist

References