Authentication & keys

The two credential types MarkDB uses, how API keys are scoped and which host accepts which.

MarkDB has two kinds of caller, and each authenticates differently:

Agents (the data plane) authenticate with an API key (mk_live_...).
Humans (the control plane) authenticate with a dashboard session after signing in with GitHub or Google.

API keys

An API key is a bearer token that identifies one agent. It looks like:

mk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The key is mk_live_ followed by 32 characters of base32-encoded entropy. MarkDB stores only a SHA-256 hash: the plaintext is shown once, at mint time, and can never be retrieved again. Lose it and you mint a new one.

Binding

Every key is bound to exactly one (account, workspace, agent) triple (see the operating model). Every request made with that key is attributed to that agent, and reads are partitioned to it. Mint one key per workspace (usually one per repo) so memory stays cleanly separated.

API naming

The API uses the older names: accounts are tenant and workspaces are app in routes and payloads (tenant_id, app_id). Same objects, different labels.

Scopes

Scope	Grants
`read`	Read data-plane endpoints: the MCP read tools, `/v1/memory/search`, `/v1/memory/detail`, `/v1/recent` and the rest of the recall surface.
`write`	Write access: proxy ingest (capture), `memory_append`, promotions, checkpoints, overlays, broadcasts. Implies `read`.

Keys minted from the dashboard carry both read and write.

Minting and revoking

Keys are managed from the dashboard (a control-plane action, so it uses your signed-in session, not an API key):

Mint: Connect or Settings -> API keys. Pick the workspace and agent, name the key, and copy the plaintext immediately.
Revoke: Settings -> API keys -> Revoke. Revocation is immediate; the next request with that key fails with 401.

Using a key

Send the key as a bearer token. The Anthropic Messages surface also accepts the Anthropic-style headers, which MarkDB maps to the same key:

# Proxy, Chat Completions / Responses, and the Memory API
-H "Authorization: Bearer mk_live_xxx"

# Anthropic Messages surface (Claude Code)
-H "x-api-key: mk_live_xxx"
# or ANTHROPIC_AUTH_TOKEN, mapped to bearer

Which host accepts which credential

Host	Credential	Purpose
`proxy.markdb.cloud/v1`	API key	LLM proxy (capture)
`mcp.markdb.cloud/mcp`	API key	MCP memory tools (recall)
`api.markdb.cloud/v1/*` (data plane)	API key	Memory API (recall + writes)
`api.markdb.cloud` (control plane)	Dashboard session	Account, workspace, agent, key and billing management

MCP never takes a dashboard session

The MCP server is agent-facing and only accepts an API key. A dashboard JWT is rejected. Humans browse memory through the dashboard Work log; agents use the key.

Bringing your own model keys

The mk_live_... key authenticates you to MarkDB. To let MarkDB call the model providers on your behalf, add your provider credentials under Settings -> LLM keys (encrypted at rest). The proxy resolves the right provider key per request based on the model name. See Models & routing.