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)

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.

​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

​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

Data Protection

Operational Safeguards

Hardening Checklist

References