Back to KeepDB

API key docs

Create admin-managed keys, restrict them to folders, revoke leaked keys, and use bearer keys from agents, scripts, apps, REST, or MCP.

Auth model

KeepDB uses two kinds of auth.

Admin Basic Auth creates, lists, and revokes API keys.
Bearer API keys read, write, search, and delete memory.

Configure admin auth

Set admin credentials on the backend service.

KEEPDB_ADMIN_USERNAME=admin
KEEPDB_ADMIN_PASSWORD=change-this-long-password

For production, prefer a SHA-256 password hash.

KEEPDB_ADMIN_USERNAME=admin
KEEPDB_ADMIN_PASSWORD_HASH=<sha256-of-admin-password>

Create the hash locally:

printf '%s' 'change-this-long-password' | shasum -a 256 | awk '{print $1}'

Do not expose admin credentials in browser code. They are only for trusted server-side operations.

Create a key

Create keys with the admin endpoint. The raw key is returned once.

curl -X POST "$KEEPDB_URL/admin/api-keys" \
  -u "$KEEPDB_ADMIN_USERNAME:$KEEPDB_ADMIN_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Claude MCP key",
    "scopes": ["memory:read", "memory:write"],
    "collection": "codex-memory"
  }'

Response

{
  "success": true,
  "apiKey": "keep_sk_...",
  "key": {
    "id": "...",
    "name": "Claude MCP key",
    "prefix": "keep_sk_...",
    "scopes": ["memory:read", "memory:write"],
    "collection": "codex-memory"
  }
}

Store apiKey immediately. KeepDB stores only its SHA-256 hash.

List keys

curl "$KEEPDB_URL/admin/api-keys" \
  -u "$KEEPDB_ADMIN_USERNAME:$KEEPDB_ADMIN_PASSWORD"

List responses never include raw API keys.

Revoke a key

Keys are revoked, not hard-deleted.

curl -X DELETE "$KEEPDB_URL/admin/api-keys/<api-key-id>" \
  -u "$KEEPDB_ADMIN_USERNAME:$KEEPDB_ADMIN_PASSWORD"

Revocation sets revoked_at. Existing memory endpoints reject revoked keys immediately.

Use a key

Normal memory endpoints use bearer auth.

curl -X POST "$KEEPDB_URL/memory" \
  -H "Authorization: Bearer keep_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "collection": "codex-memory",
    "content": "Remember that the API key flow is admin-created and bearer-used.",
    "metadata": {
      "tags": ["api-keys", "docs"]
    }
  }'

Search memory:

curl "$KEEPDB_URL/memory?collection=codex-memory&query=api%20key" \
  -H "Authorization: Bearer keep_sk_..."

Scopes

memory:read: search, list collections, list memories, inspect stats.
memory:write: create memories.
memory:delete: soft-delete memories.

New keys default to ["memory:read", "memory:write"].

Folder restrictions

If collection or folder is provided when creating a key, that key is restricted to that folder. If no folder is provided, the key can access all folders owned by that user, subject to its scopes.

MCP endpoint

The same bearer key can connect agents through MCP.

https://api.keepdb.dev/mcp
Authorization: Bearer keep_sk_...