Authentication
Exchange your API key for a short-lived token, on your server.
API key and token
Section titled “API key and token”Your team has an API key. Your backend exchanges it for a token with POST /token, and sends the token as Authorization: Bearer <token> on every other request.
curl -s -X POST "$ENGINE/token" \ -H "Content-Type: application/json" \ -d '{"apiKey":"<your-api-key>"}'{ "token": "<jwt>", "expiresIn": 3600 }expiresIn is in seconds. Read it from the response instead of assuming a value.
With the SDK: no token in the browser
Section titled “With the SDK: no token in the browser”The recommended path: your page talks to your backend, and your backend’s proxy adds the token. The browser never carries a key or a token, and your page creates the client without getToken. The token source mints with your key, caches the token and mints once more after a 401; it reads the key when it is created, so after a rotation restart your backend. Build the proxy in Your backend.
import { createTokenSource } from '@neurologyca/capture-server'
const tokens = createTokenSource({ baseUrl: process.env.ENGINE_BASE, apiKey: process.env.ENGINE_API_KEY })const { token, expiresAt } = await tokens.get() // what the proxy puts in Authorization; never send it to the pageKeep the key on your server
Section titled “Keep the key on your server”- Anyone with the key can mint tokens for your organization. Treat the token as a secret too: it is not limited to one user or one capture (a capture token is).
- Without
@neurologyca/capture-server(the HTTP API, or a proxy of your own), your backend mints the token, keeps it and puts it in theAuthorizationof its own calls to Engine, behind your own authentication; never hand it to the page. See Proxy by hand.
// Your backend without @neurologyca/capture-server: it mints Engine's token with your key and keeps it on the server.// The token goes in the Authorization of your proxy's calls to Engine, never to the page.const ENGINE = process.env.ENGINE_BASE // the Engine URL of your kitlet cached = null // { token, expiresAt }let minting = null // the request in flight: calls that arrive meanwhile share it instead of minting another token
export function engineToken(now = Date.now()) { if (cached && cached.expiresAt - 60_000 > now) return Promise.resolve(cached.token) // reuse it until a minute before it expires minting ??= mint(now).finally(() => { minting = null }) return minting}
async function mint(now) { const r = await fetch(`${ENGINE}/token`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ apiKey: process.env.ENGINE_API_KEY }), }) if (!r.ok) throw new Error(`POST /token answered ${r.status}`) // 401: the key is wrong, revoked or expired const { token, expiresIn } = await r.json() cached = { token, expiresAt: now + expiresIn * 1000 } return token}Cache and renew
Section titled “Cache and renew”POST /tokenis rate limited per client IP. Mint once and reuse the token until shortly before it expires; do not mint one per request.- There is no refresh endpoint: when the token is about to expire, call
POST /tokenagain.
Rotation and revocation
Section titled “Rotation and revocation”When a key is rotated or revoked, it stops minting new tokens at once, and a token minted from it is refused on its next request (401). Mint a new token with the new key. See Keys: rotation, revocation and expiry and the access model.
Scopes
Section titled “Scopes”Each key has a scope, admin or read_all. A read_all key only reaches the users it created: their captures, results, interpretations, events and management (enrol, block, delete). It still lists and edits every user of the organization. See Access model.
A token for one capture
Section titled “A token for one capture”POST /token/capture returns a token limited to one capture, for whoever sends a recording without needing your token: for example, the processing service. Your backend calls it with its regular token (Authorization: Bearer) and the capture’s three ids:
{ "userProtocolId": "00000000-0000-4000-8000-9ca46ec3ea86", "protocolMechanicId": "00000000-0000-4000-8000-c9d097234e8d", "captureId": "00000000-0000-4000-8000-07f0d35d38d2"}- It lasts 30 minutes (
expiresIn: 1800). When it expires, request another one. - It only allows sending that capture (
captureId) of that mechanic:POST …/context,POST /process-kpn-emo,GET …/sessions,POST …/cancel,GET /results/{userProtocolId}/{protocolMechanicId},GET /user-protocols/{userProtocolId},GET /user-protocols/{userProtocolId}/mechanics/{protocolMechanicId},GET /user-protocols/{userProtocolId}/schemaandGET /stream/{userProtocolId}. OnPOST …/contextandPOST …/cancelyou can leavecaptureIdout: the token’s is used.POST /process-kpn-emomust carry it, so pass the SDK the samecaptureId. With it, the stream only carries that mechanic’s events and closes withstream.endandreason: "token_expired"when the token expires. - Any other route, mechanic or capture,
POST /analyzeamong them, answers403withreason: "CAPTURE_TOKEN_SCOPE". A capture token cannot request another one. Rotating, revoking or deleting your key invalidates it at once. - Its requests are limited per capture and per minute: 15 for
GET …/schemaandPOST …/contexttogether, 30 forPOST /process-kpn-emoand 60 for the rest. Above that it answers429withreason: "CAPTURE_TOKEN_RATE_LIMIT"and aRetry-Afterheader: nothing was processed, wait those seconds and repeat. A new token for the samecaptureIdkeeps the count. Your regular token has no such limit. Since@neurologyca/capture0.37.0 the SDK waits thatRetry-Afterand sends the same request again (at most 2 minutes at a time and 5 times in a row), with the warningtransport.rate-limited;canceldoes not wait. Earlier versions fail the capture. - For everything else, your backend keeps using its regular token.
Today only the test environment’s Engine has this route; production does not yet.
Errors
Section titled “Errors”| Status | When | Body |
|---|---|---|
401 on /token |
The key is malformed, unknown, revoked or expired, or your organization is suspended (the same answer in every case) | { "code": 401, "message": "Invalid credentials." } |
401 elsewhere |
Missing, expired or invalid token, or its key was rotated, revoked or has expired | Empty body, with a WWW-Authenticate: Bearer header |
429 on /token |
Too many token requests from your IP | Empty body |
In DevLab
Section titled “In DevLab”- Your team’s key is in Your account. Revealing it asks for your password, is limited to 5 times per hour and is recorded.
- The playground never asks for a token from the browser:
POST /tokenandPOST /token/capturedon’t go through DevLab. Your backend mints tokens.