API keys
Mint a read-only dbk_live_ or dbk_test_ key for the content snapshot API.
Last updated on
Data API keys are not the install write key. The write key starts with dbw_ and is only for POST /v1/collect. A data API key starts with dbk_live_ or dbk_test_ and is only for the read API. A legacy dbr_ read key is not accepted. The dashboard itself still uses your Clerk session.
Create keys at databob.dev/dashboard/api-keys.
Who can do what
An owner or admin creates, names, lists, and revokes keys for one explicit org. A member of that org can list keys. Members do not see who created a key.
A key is read-only. Scope is one site, or every site in the org. There is no write scope. The full secret is shown once. Convex stores an HMAC-SHA256 of the secret, not the secret. The prefix is a label. Authorization is the HMAC.
An org can have 25 active keys. Revoking a key frees a slot. lastUsedAt is updated at most once a minute on a request that is allowed through.
Which prefix you get
| Deployment | New keys |
|---|---|
Production (savory-yak-367) | dbk_live_, even if the mode is unset or test |
| Anywhere else | dbk_test_, unless DATA_API_KEY_MODE is live |
Set DATA_API_KEY_MODE to live on production anyway. The pepper DATA_API_KEY_PEPPER has to be set on the Convex deployment before a key can be created. It is not trimmed. Without it, key creation fails and the read routes return 500 with { "error": "unavailable" }.
Send it
Authorization: Bearer dbk_live_REPLACEA missing, unknown, or revoked key is 401. The install write key in that header is 401 as well.
SDKs are not published
There is no official client library yet. Call https://api.databob.dev with the header above. The machine-readable contract is docs/data-api.openapi.yaml, and info.version is 1.
Pepper rotation, for operators: copy the current pepper into DATA_API_KEY_PEPPER_PREVIOUS without trimming either value, set a new DATA_API_KEY_PEPPER, and deploy. Keys hashed with the previous pepper stay valid while that variable is set and hashVersion is still 1. Unset the previous pepper when those older keys should stop working. Do not bump the hash version for a pepper rotation. That invalidates every key.