API Keys

​

The two surfaces, side by side

​

Scope vocabulary

​

Scope semantics — what to know

• Capabilities are independent. admin:platform does NOT imply api:read. A key with only admin:platform cannot call /v1/agents. If your automation needs to call non-admin endpoints alongside admin ones, request both.
• Mint-time ceiling is enforced server-side. Requesting a scope you’re not eligible for returns HTTP 403 at creation time. Examples:
  POST /v1/api-keys
  { "name": "doomed", "scopes": ["admin:platform"] }
  ← 403 admin:platform scope requires Mnemom-staff role on your account
  
• Request-time role is re-checked for admin scopes. If a staff member is demoted after minting an admin:platform key, that key’s admin power stops working immediately on the next request — without rotation. The key still authenticates for non-admin endpoints if those scopes are also present.
• Demotion is silent. Mnemom does not auto-revoke admin-scoped keys when a user’s role changes. Use DELETE /v1/api-keys/{key_id} (or rotate) when offboarding admin-role users.

​

Picking scopes for common patterns

• Local development on your laptop: gateway, api:read, api:write (the default).
• CI runner that publishes traces but doesn’t mutate state: gateway, api:read.
• Read-only analytics ingest into Snowflake/BQ: api:read.
• Service account that manages org members from a script: admin:org (plus api:read if it needs to read non-admin endpoints).
• Mnemom-internal automation (deploy gates, on-call tooling): admin:platform (plus api:read/api:write if it touches non-admin endpoints too).

​

When to use which surface

• Local development. A developer on the team using Mnemom from their laptop. Personal key.
• Per-engineer CI accounts. Each engineer has their own CI runner credentialed against their personal account. Personal key.
• Single-purpose script you’re running yourself. Personal key.

• Shared CI/CD infrastructure that runs as the org, not as a specific engineer. Survives engineer turnover.
• Service-account-style automation — a cron job, a webhook receiver, a third-party integration that needs to outlive any individual member’s tenure.
• Audit / compliance posture that needs requests attributed to the org rather than to a person. The audit log tags org-level keys distinctly from user-level keys.

​

Creating a key

​

Personal

curl -X POST https://api.mnemom.ai/v1/api-keys \
  -H "Authorization: Bearer $MNEMOM_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "local dev",
    "scopes": ["gateway", "api:read", "api:write"]
  }'

​

Organization

curl -X POST https://api.mnemom.ai/v1/orgs/$ORG_ID/api-keys \
  -H "Authorization: Bearer $MNEMOM_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ci-prod",
    "scopes": ["gateway", "api:read", "api:write"]
  }'

{
  "key_id": "mk-1a2b3c4d",
  "key": "mnm_8f3e7c2b91a4d6f8...",
  "key_prefix": "mnm_8f3e",
  "name": "ci-prod",
  "scopes": ["gateway", "api:read", "api:write"],
  "created_at": "2026-04-25T12:34:56Z"
}

​

Using a key

curl https://api.mnemom.ai/v1/agents \
  -H "X-Mnemom-Api-Key: mnm_8f3e7c2b91a4d6f8..."

​

Legacy keys (["gateway", "api"])

1. Rotate the key (POST /v1/api-keys/{key_id}/rotate) — the rotation preserves the legacy scope set on the new key.
2. Revoke the rotated key and create a fresh one (POST /v1/api-keys) without specifying scopes. The new key inherits the default ["gateway", "api:read", "api:write"].

​

Rotation

• POST /v1/api-keys/{key_id}/rotate
• POST /v1/orgs/{org_id}/api-keys/{key_id}/rotate

​

No grace period — by design

1. POST /v1/api-keys to create a second key.
2. Update your deployment to use the new key.
3. Verify it’s working in production.
4. DELETE /v1/api-keys/{old_key_id} to retire the original.

​

Failure semantics

• Insert-new fails: the response is 500; your old key is still valid. Try again.
• Insert-new succeeds, soft-revoke fails: the response is 500 with a hint pointing you at DELETE /v1/api-keys/{old_key_id} to finish manually. The new key is fully active either way — capture it before retrying.

​

Audit trail

​

Org keys after P4f tightening

1. Use a personal key instead. They’re billed to you, but Mnemom doesn’t double-bill — the personal-key checkmeter is a courtesy view, not a separate ledger.
2. Or ask an admin to create the org key for you. Once it exists, you can rotate it (you become the creator post-rotation) but only the admin can have created it initially.

​

Revocation

curl -X DELETE https://api.mnemom.ai/v1/api-keys/mk-1a2b3c4d \
  -H "Authorization: Bearer $MNEMOM_JWT"

​

Key hygiene checklist

• Rotate annually, or whenever a member with access leaves the org. The audit log shows last_used_at per key — rotate dormant keys aggressively.
• Name your keys. "name": "ci-prod" is much more useful than "Default" six months later when you’re triaging an alert.
• Use the smallest scope set that works. Default to gateway + api:read/api:write and only add admin scopes when the integration genuinely needs them. Smaller blast radius if leaked.
• Prefer api:read for analytics integrations. Read-only keys are safer and the audit trail is cleaner.
• Never commit secrets. The mnm_ prefix is a string git secret-scanners recognize; we recommend GitHub Secret Scanning + push protection to catch accidents.
• Include a renewal reminder in your deploy / IaC if the key has a TTL constraint from your security policy. Mnemom keys themselves don’t expire by default.
• Treat admin-scope keys with extra care. Use them only for the specific automation that needs them; rotate them on any suspected leak; audit which keys carry admin:org or admin:platform quarterly.