Authentication

Authentication

A key’s ID and secret as two headers, or a signed request instead.

Example request

A first callbash
curl "https://console.brevily.com/api/NORTHWIND/links?limit=10" \  -H "x-api-key: brv_ak_7Fq2Lw9xK3" \  -H "x-api-secret: $BREVILY_SECRET"

Example answer

With a secret that does not matchhttp
HTTP/1.1 401 Unauthorized{  "code": "UNAUTHENTICATED",  "message": "invalid credential",  "requestId": "18188559082372202519"}
A signed request sent twice (x-nonce)http
HTTP/1.1 401 Unauthorized{  "code": "UNAUTHENTICATED",  "message": "signature nonce already used within the accepted window",  "details": { "reason": "NONCE_REUSED" },  "requestId": "18188559082372202519"}

Made-up values.

Every call carries one of an organisation’s API keys. Send it one of two ways: its ID and secret as two headers, or a signature made with the secret, so the secret itself never travels. Both work on every call.

The key headers
NameTypeRequiredDescriptionAllowed values
x-api-keyheaderrequiredThe key’s ID, shown in the console’s API keys.—
x-api-secretheaderrequiredIts secret, shown once when the key is made. Keep it on a server.—

Which key acts howPermalink

An organisation’s key acts for the organisation, with the permissions it was given, whoever made it, and keeps working when its maker leaves. A personal key acts as the person who made it, within the permissions it was given and what that person holds now; making or rolling one asks for their password. Either answers only for its own organisation. Keys are made, rolled, revoked and listed in the console only, by someone signed in: no key can call those.

Signing a requestPermalink

To keep the secret off the wire, send four headers instead of the two: x-key-id (the key’s ID), x-timestamp (now, in whole Unix seconds), x-nonce (a value of your own, new for every request, 1 to 128 characters: a UUID does) and x-signature. The signature is HMAC-SHA256 under the secret, in lowercase hex, over these lines joined by a newline:

What a request signs
NameTypeDescriptionAllowed values
1lineThe method, in capitals: GET.—
2lineThe path as sent, /api and the query string included: /api/NORTHWIND/links?limit=10.—
3lineThe x-timestamp header’s value, as sent.—
4lineThe x-nonce header’s value, as sent (echoed on the answer).—
5linesha-256=:<base64>:, the SHA-256 of the exact body bytes in base64 (an empty body’s for a GET).—

A timestamp more than 5 minutes from the server’s clock is refused, and each nonce works once: the same nonce from the same key inside 10 minutes is refused, so a captured request can never be sent again. The answer comes back signed the same way, over its status, its own x-timestamp, your nonce (echoed in x-nonce) and its body’s digest: check it with the same secret to know the answer is to your request.

What is signed (made-up values)text
GET/api/NORTHWIND/links?limit=1017908464074c3e1f0a-8a5d-4f8e-9b7c-2d6e5a1b0c93sha-256=:47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=:

With the made-up secret brv_made_up_secret_for_this_page, those lines sign to 2dc6b2c8eb57de99849f2b64aed963a9f5c9fa402e12bb89fa04ed391471042e.

Nodejavascript
import { createHash, createHmac, randomUUID } from 'node:crypto';// path: as sent, with /api and the query; body: the exact text sent.// Call it for every request, retries included: each needs a new nonce.function sign(keyId, secret, method, path, body = '') {  const t = String(Math.floor(Date.now() / 1000));  const nonce = randomUUID();  const digest = 'sha-256=:' +    createHash('sha256').update(body).digest('base64') + ':';  const signature = createHmac('sha256', secret)    .update([method, path, t, nonce, digest].join('\n'))    .digest('hex');  return {    'x-key-id': keyId,    'x-timestamp': t,    'x-nonce': nonce,    'x-signature': signature,  };}

The lines use RFC 9421’s component names, not its wire format: an RFC 9421 client library will not produce them. The console’s guide on authentication has the same, for someone signed in.

When it mattersPermalink

The two headers suit a server you control: simple, and the secret stays behind TLS. Sign when the secret should never cross a network at all, or when a request passing through others’ hands (a proxy, a queue, a log) must not be replayable. A refusal for either is 401 UNAUTHENTICATED; a signed request names its own fault in details.reason: STALE_TIMESTAMP, INVALID_NONCE or NONCE_REUSED.

Common mistakesPermalink

  • Putting the secret in a browser or a mobile app. Anyone can read it there; call from your server.
  • Sending a console session or a Bearer token: /api refuses both, even for someone signed in. So does Authorization: ApiKey …; use the two headers.
  • Signing a retry with the nonce of the first attempt: it is refused as NONCE_REUSED. Sign every attempt again.
  • Signing the path without /api or without its query string, or signing the body before it is serialised the way it is sent. The digest is of the exact bytes.
  • A server clock that drifts: past 5 minutes every signature fails as STALE_TIMESTAMP. Keep it set by NTP.