Developers

On this page
Using the API

Authentication

Every call except /v2/meta needs an access token. You get one by sending your API key and its secret to /v2/auth/token, then send the token with every read until it expires.

Get a token

Send the key in the x-api-key header and the secret in x-secret-auth-key:

Shell
curl https://api.blazot.com/v2/auth/token \
  --header "x-api-key: $BLAZOT_API_KEY" \
  --header "x-secret-auth-key: $BLAZOT_API_SECRET"
JSON
{
  "tokenType": "bearer",
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6...",
  "expiresIn": 30000
}
  • tokenType is always bearer.
  • accessToken is the token: send it on every other call as Authorization: Bearer {accessToken}.
  • expiresIn is how many seconds the token lasts from now (30,000 today, a little over eight hours).

The key and secret go only to this call. No other endpoint takes them, so they never need to leave the part of your server that asks for tokens.

Keep the token and reuse it

The token call has its own small limit: 3 requests per 5 minutes for each account. Asking for a token before every read would hit it at once, so get one, keep it, and reuse it:

  • Keep it in memory on your server, shared by everything that calls the API.
  • Note when it expires (now plus expiresIn seconds), and get a new one a minute or so before then.
  • If a read answers 401 with a WWW-Authenticate header, the token has expired or stopped working: get a new token once and retry. If that call fails too, stop and look at its error rather than trying again.

Failed token requests count against the same limit. A request whose key the API can't tie to a usable account (a missing or unknown key, or one for an account that can't be used) is counted by the key's value instead.

When the token call fails

A failed token call is a 401 with a Problem Details body whose code is unauthorized. Its detail is one of two messages:

detail What it means What to do
Invalid API credentials. The key or the secret is missing, wrong or unknown, or the account is disabled, deleted or suspended. One message covers them all, so the API doesn't reveal which. Check you're sending the current key and secret. If you regenerated them, use the new pair. If you know they're right, try again in a few minutes before regenerating them.
Account is unavailable. The key and secret are right, but the account can't use the API right now: its subscription payment is past due. For a Site's key, the same applies when the Site's own subscription or its owner's is past due, or the owner is unavailable. Fix the account on Blazot. A new token won't help until then.

A problem at Blazot, such as a brief outage while it looks up your key, is usually a 500 with the code server-error. Try again a little later.

Too many token requests get a 429 with a Retry-After header: wait that many seconds, plus one: Errors says why, and has the full list.

What makes a token stop working

A token works until it expires, unless one of these happens first:

  • The keys are regenerated. Every token from the old key stops working at once: get a new token with the new key and secret.
  • The account becomes unavailable. For a Site's key, the same happens when the Site's own subscription or its owner's goes past due, or the owner becomes unavailable. From the next read on, reads are refused, and a new token won't help until the account is fixed.

Either way, reads answer 401; Errors lists each detail and what to do.

Regenerate your keys

Regenerate them on your Configuration page, or on a Site's configuration page for a Site's key, under API Keys. Do it whenever the key or secret may have been seen by someone else. The old key and its tokens stop working at once, so update your server with the new pair right away.

Keep the token secret

A token is as good as your key until it expires: anyone who has it can read as your account. Treat it like the secret:

  • Keep it on your server, in memory: the token response tells caches not to store it (Cache-Control: no-store). Never send it to a web page or an app.
  • Don't write it to logs, error reports or URLs.
  • If it may have leaked, regenerate your keys: that's the only way to stop a token before it expires.