Authentication
Authentication
A key’s ID and secret as two headers, or a signed request instead.
Example request
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
HTTP/1.1 401 Unauthorized{ "code": "UNAUTHENTICATED", "message": "invalid credential", "requestId": "18188559082372202519"}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.
| Name | Type | Required | Description | Allowed values |
|---|---|---|---|---|
x-api-key | header | required | The key’s ID, shown in the console’s API keys. | — |
x-api-secret | header | required | Its 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:
| Name | Type | Description | Allowed values |
|---|---|---|---|
1 | line | The method, in capitals: GET. | — |
2 | line | The path as sent, /api and the query string included: /api/NORTHWIND/links?limit=10. | — |
3 | line | The x-timestamp header’s value, as sent. | — |
4 | line | The x-nonce header’s value, as sent (echoed on the answer). | — |
5 | line | sha-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.
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.
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
Bearertoken:/apirefuses both, even for someone signed in. So doesAuthorization: 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
/apior 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.