Authenticate with the document extraction API

Send your key as a bearer token

Every request carries the key in the Authorization header. This call to the usage endpoint is a safe way to check that a key works, because it reads your quota and doesn't use any pages.

curl "$DOCREFINERY_API/v1/usage" \
  -H "Authorization: Bearer $DOCREFINERY_API_KEY"

import os

import requests

response = requests.get(
    f"{os.environ['DOCREFINERY_API']}/v1/usage",
    headers={"Authorization": f"Bearer {os.environ['DOCREFINERY_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
print(response.json()["pages_remaining"])

const response = await fetch(process.env.DOCREFINERY_API + "/v1/usage", {
  headers: { Authorization: "Bearer " + process.env.DOCREFINERY_API_KEY },
});
if (!response.ok) throw new Error("Request failed: " + response.status);
console.log((await response.json()).pages_remaining);

$DOCREFINERY_API stands for the API base URL, https://api.docrefinery.com.

How API access is switched on

API keys are not self-serve. docRefinery switches them on for each account, separately from your plan, so contact us to ask. Until then the API keys tab doesn't appear in Settings and api_keys_enabled is false in the usage response. If access is later switched off, existing keys are refused within a minute.

Who can create and manage keys

In an organisation, owners and admins manage the organisation's keys; members can't. A user with no organisation manages their own. Key management happens only in the dashboard: an API key can't create or revoke keys, so a leaked key can't mint another.

Create a key

1. Open Settings, then API keys, and choose Create key.
2. Name it after what it is for, such as ERP sync, so you can recognise it later. Names can be up to 100 characters.
3. Choose when it expires: 30 days, 90 days, 1 year or never.
4. Copy the secret and store it somewhere safe, then tick the box to confirm you've done so.

Keep keys on your server

A key acts for your whole account, so treat it like a password. Call the API from your own backend and read the key from a secret store or a server-side variable. Never put it in a web page or a mobile app. The API doesn't accept browser requests from other sites in any case, so a call from your own front end fails as well as exposing the key.

What a key can do

A key lets your own systems send documents and read the results. All the endpoints in these docs accept one. A key can't manage users, organisations or settings. Every key on an account draws on the same monthly pages and the same rate limit, so a second key doesn't add capacity.

Revoke a key and check its activity

To revoke a key, open its row menu under Settings, then API keys, and choose Revoke. Anything using it stops working within a minute, and this can't be undone. To replace a key without downtime, create the new one, deploy it, then revoke the old one.

View activity on the same menu lists the key's write requests, such as document submissions, for the last 90 days. Reads aren't listed. The last-used time on each key updates at most once a minute.