Skip to main content
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.

​
Namespace Isolation

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

​
Dual Identifier Model

IdentifierVisible?Purpose
organization_idYesUser-facing identifier in API responses
internal_idNoPrimary key for service-to-service lookups
namespace_idYesIsolation 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 consume credits; 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..."
  }'

​
Bring Your Own Key (BYOK)

Use your own LLM API keys in retriever stages instead of Mixpeek’s default keys. This gives you:
BenefitDescription
Cost ControlUse your own API credits and billing
Rate LimitsUse your own rate limits instead of shared
ComplianceKeep API calls under your own account
Key RotationRotate keys without modifying retrievers

​
Supported Providers

ProviderSecret Name ExampleModels
OpenAIopenai_api_keygpt-4o, gpt-4o-mini
Anthropicanthropic_api_keyclaude-3-haiku, claude-3-sonnet, claude-3-opus
Googlegoogle_api_keygemini-2.0-flash, gemini-1.5-pro

​
Using BYOK in Retrievers

Reference secrets in LLM stages using template syntax: 
{
  "stages": [
    {
      "stage_type": "apply",
      "stage_id": "llm_enrich",
      "parameters": {
        "provider": "openai",
        "model": "gpt-4o-mini",
        "prompt": "Summarize this document.",
        "output_field": "summary",
        "api_key": "{{secrets.openai_api_key}}"
      }
    }
  ]
}
The {{secrets.secret_name}} syntax automatically resolves the secret from your organization’s vault at runtime.
When api_key is omitted, stages use Mixpeek’s default API keys and usage is charged to your Mixpeek account.

​
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, Qdrant Cloud, 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 Qdrant; 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

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

​
References