API Keys

Manage your API keys — create, scope, rotate, and revoke.

Key Format

API keys follow the format: jdb_sk_<env>_{secret}

jdb_sk_live_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0

Key Components

Name	Type	Description
`jdb_sk`	prefix	Identifies this as a jsondb.cloud secret key
`live / test`	env	'live' for production, 'test' for development
`{secret}`	string	40-character random secret

Key Scoping

Each key has a scope that controls what operations it can perform:

Available Scopes

Name	Type	Description
`read-write`	scope	Full access: create, read, update, delete documents
`read-only`	scope	Can only GET documents. POST/PUT/PATCH/DELETE return 403 Forbidden.

lightbulb

Best practice

Use read-only keys for frontend applications and read-write keys for server-side code.

Key Rotation

Rotate a key to get a new secret while keeping the same name and configuration. The old key is immediately revoked.

POST /api/keys/{keyId}/rotate
Authorization: Bearer <session cookie>

Response (201):
{
  "apiKey": { ... },
  "rawKey": "jdb_sk_live_NEW_SECRET_HERE"
}

Rate Limiting

API requests are rate-limited per key:

Rate Limits

Name	Type	Description
`Free tier`	10 req/s	10 requests per second per API key
`Pro tier`	100 req/s	100 requests per second per API key

Rate limit info is included in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1708814400

Key Limits

Plan Limits

Name	Type	Description
`Free`	2 keys	Maximum 2 active API keys
`Pro`	20 keys	Maximum 20 active API keys