Authenticate with an API key

One header, x-api-key, authenticates every call. The API keeps no session and issues no token.

Send the key in a header

curl

curl https://api.urakimon.com/usage \
  -H "x-api-key: $URAKIMON_API_KEY"

The key must travel in the header. A key in the query string is refused with 401, because query strings end up in access logs and browser history:

401 response

{ "ok": false, "error": "invalid api key: send it in the x-api-key header, not the query string" }

Manage keys on the account page

Keys are created, rotated and revoked at https://api.urakimon.com/account. An account holds up to 5 active keys.

Create: the secret starts with urakimon_ and is shown once. Only a hash of it is stored, so it cannot be shown again.
Rotate: the key keeps its id, its usage and its quotas, and gets a new secret. The old secret stops working the moment the rotation completes, so update the places that hold it first if you cannot afford a gap.
Revoke: permanent. A revoked key answers 401 from then on. Any of its jobs still queued are cancelled before they start with the error cancelled before start: the API key was revoked or suspended; any already running are stopped at once with cancelled: the API key was revoked. The records a running job had already delivered stay readable and billed.

Note. Each key has its own webhook signing secret (whsec_...), shown next to the key on the account page. It is derived from the key id, so it stays the same when you rotate the secret. See Webhooks.

401 unauthorized

{ "ok": false, "error": "invalid api key" } means the API could not match the header to an active key: the header is missing, the secret is mistyped, or the key was revoked. Check the variable the header is read from, then the account page.

After 20 failed attempts from one address within 60 seconds, further requests from that address get 429 with too many failed auth attempts; retry later. Fix the key before retrying; a loop that keeps sending a bad key stays locked out.

402 payment required

The key is valid, but its account cannot spend right now: no credit is left, or a payment dispute holds the account. The message names the reason and the fix. A 402 never counts as a failed attempt.

Message	What to do
`insufficient credits: this account's balance is used up. Buy credits at /account to continue`	Buy credit under Credits on https://api.urakimon.com/account. The key resumes as soon as the balance is positive.
`account on hold while a payment dispute is open: contact URAKIMON support`	Write to support. The hold lifts when the dispute closes.

Creating a key needs no credit at all: it works the moment the account exists. Credit is only needed to fetch records. Pricing and billing explains what is charged and how to buy credit.

Next step

With a working key, read Records and jobs to choose between waiting for the response and submitting a job.