Authentication

API keys, and what you can do without one.

Send your key in either header:

-H "Authorization: Bearer dbk_live_..."
-H "x-api-key: dbk_live_..."

Kinds of key

Key	Starts with	Where it comes from	What it spends
Account key	`dbk_live_`	The dashboard	The pages on your plan
Credit key	`dbk_pack_`	Pay per use	The pages it was bought with

A new account's first key is shown once on the dashboard, and you can create more there. Copy a key when you create it. Only a hash is stored, so it can't be shown again. If a key leaks, revoke it from the dashboard and make a new one.

Without a key

POST /v1/convert works without a key. It reads the first page of a file, 3 times a day. There's also a limit on free conversions across all users each day, so they can run out sooner.

When they've run out, you get 402 with a payment challenge if pay per use is on, and otherwise 429 free_limit_reached. See Errors.

What needs a key

Endpoint	Key
`POST /v1/convert`	Optional
`GET /v1/jobs/{id}`	Not needed
`GET /v1/jobs/{id}/result.{format}`	Not needed
`GET /v1/usage`	Required

Reading a job needs only its id, so treat ids as private. Each one is a long random string that can't be guessed.

Check your usage

curl https://api.docbeast.com/v1/usage -H "Authorization: Bearer dbk_live_..."

With an account key:

{
  "kind": "plan",
  "plan": "starter",
  "period": "2026-11-01T00:00:00Z",
  "pages_used": 42,
  "pages_included": 100,
  "pages_remaining": 58
}

With a credit key:

{ "kind": "credits", "pages_remaining": 25 }

period is your subscription's start on a paid plan, or the month (2026-11) on the Free plan.

OAuth

AI clients that connect to the MCP server can sign in with OAuth, so you don't have to paste a key. Those access tokens only work on the MCP server, not on the REST API.