Authentication
Every request to Mnemexa carries a workspace API key in the Authorization header. Keys are workspace-scoped — one key = one workspace.
The key format
Workspace API keys look like:
mnx_ws_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0| Part | Meaning |
|---|---|
mnx_ws_ | Fixed prefix. Identifies this as a Mnemexa workspace key. |
| 40 hex chars | The random secret material (160 bits of entropy). |
The first 14 characters (e.g. mnx_ws_a1b2c3d) are stored as the key’s display prefix — you’ll see this in the dashboard and in status responses to identify which key is in use without exposing the secret.
Legacy keys generated before the 2026-05 rebrand use the bxk_ws_ prefix. They continue to work and are accepted exactly as mnx_ws_ keys. New keys are issued with the new prefix.
Sending the key
Include it as a Bearer token on every request:
GET /v1/status HTTP/1.1
Host: api.mnemexa.com
Authorization: Bearer mnx_ws_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0The SDK and MCP adapter both read the key from environment variables — you only handle the value when first storing it:
export MNEMEXA_API_KEY=mnx_ws_…The Python SDK also accepts the legacy BIZX_API_KEY env var as a fallback so v1 users don’t have to re-export. New deployments should use MNEMEXA_API_KEY.
Provisioning keys
Keys are created in the dashboard at app.mnemexa.com:
- Open the workspace.
- Navigate to Settings → API Keys.
- Click Create new key, give it a label (e.g.
production-backend,local-dev), and copy the value.
The full key is shown once. After you close the dialog, only the prefix remains visible. Lost a key? Revoke it and issue a new one.
Rotating and revoking
From the same Settings → API Keys page:
- Disable — pauses the key without deleting it. Re-enabling restores the same secret.
- Regenerate — issues a new secret on the same key record. The old value is invalidated immediately.
- Delete — permanently removes the key.
Multiple active keys per workspace are allowed (subject to your plan’s key limit). Use a separate key per environment so you can rotate one without disrupting the others.
What auth checks (and what it doesn’t)
The auth middleware validates the key string itself and resolves it to a workspace. It does not check workspace status — a suspended or limit_reached workspace still passes auth, and the per-endpoint logic decides whether to accept or reject the call:
| Status | /v1/status | /v1/optimize/health | /v1/memory/store · /v1/memory/retrieve |
|---|---|---|---|
active | 200 | 200 | 200 |
pending_payment | 200 | 200 | 200 (until cap) |
suspended | 200 | 200 | 403 |
limit_reached | 200 | 200 | 429 |
This split exists so you can use status and optimize.health to debug why memory calls are failing.
Error responses
| Status | Cause |
|---|---|
| 401 | Missing Authorization header, malformed header (not Bearer …), empty key, or unknown key. |
| 403 | Key recognized but disabled, workspace deleted, or client account suspended. |
See Errors for the full response-shape conventions.
Secret hygiene
- Never commit API keys to source control. Use a secrets manager.
- Never expose API keys in browser code or client-side bundles. The SDK is server-side only.
- Never log full API keys. Logging the
prefix(first 14 chars) is safe. - If a key leaks, regenerate it immediately. Mnemexa cannot un-leak a key, only invalidate it.