Ir al contenido
DevLab

Tu equipo tiene una API key. Tu backend la cambia por un token con POST /token y envía el token como Authorization: Bearer <token> en todas las demás peticiones.

Shell
curl -s -X POST "$ENGINE/token" \
-H "Content-Type: application/json" \
-d '{"apiKey":"<your-api-key>"}'
JSON
{ "token": "<jwt>", "expiresIn": 3600 }

expiresIn va en segundos. Léelo de la respuesta en vez de dar un valor por hecho.

El camino recomendado: tu página habla con tu backend y el proxy de tu backend pone el token. El navegador nunca lleva una key ni un token, y tu página crea el cliente sin getToken. La fuente de tokens acuña con tu key, guarda el token y vuelve a acuñar una vez tras un 401; lee la key al crearse, así que tras una rotación reinicia tu backend. Monta el proxy en Tu backend.

JavaScript
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() // lo que el proxy pone en Authorization; nunca se lo envíes a la página
  • Cualquiera con la key puede pedir tokens de tu organización. Trata también el token como un secreto: no está limitado a un usuario ni a una captura (un token de captura sí).
  • Sin @neurologyca/capture-server (la API HTTP, o un proxy propio), tu backend pide el token, lo guarda y lo pone en el Authorization de sus propias llamadas a Engine, detrás de tu propia autenticación; nunca se lo entregues a la página. Ver Proxy a mano.
JavaScript
// 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 kit
let 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
}
  • POST /token tiene un límite de peticiones por IP de cliente. Pide un token una vez y reutilízalo hasta poco antes de que caduque; no pidas uno por petición.
  • No hay endpoint de renovación: cuando el token esté a punto de caducar, vuelve a llamar a POST /token.

Cuando una key se rota o se revoca, deja de emitir tokens nuevos en el acto, y un token emitido con ella se rechaza en la siguiente petición (401). Pide un token nuevo con la key nueva. Ver Keys: rotación, revocación y caducidad y el modelo de acceso.

Cada key tiene un scope, admin o read_all. Una key read_all solo alcanza a los usuarios que creó: sus capturas, resultados, interpretaciones, eventos y gestión (inscribir, bloquear, borrar). Aun así, lista y edita a todos los usuarios de la organización. Ver Modelo de acceso.

POST /token/capture devuelve un token limitado a una captura, para quien envía una grabación sin necesitar tu token: por ejemplo, el servicio de procesado. Tu backend lo pide con su token normal (Authorization: Bearer) y los tres ids de la captura:

JSON
{
"userProtocolId": "00000000-0000-4000-8000-9ca46ec3ea86",
"protocolMechanicId": "00000000-0000-4000-8000-c9d097234e8d",
"captureId": "00000000-0000-4000-8000-07f0d35d38d2"
}
  • Dura 30 minutos (expiresIn: 1800). Cuando caduca, pide otro.
  • Solo permite enviar esa captura (captureId) de esa mecánica: 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}/schema y GET /stream/{userProtocolId}. En POST …/context y POST …/cancel puedes omitir captureId: se usa el del token. POST /process-kpn-emo tiene que llevarlo, así que pasa al SDK el mismo captureId. Con él, el stream solo trae los eventos de esa mecánica y se cierra con stream.end y reason: "token_expired" cuando el token caduca.
  • Cualquier otra ruta, mecánica o captura, POST /analyze incluida, responde 403 con reason: "CAPTURE_TOKEN_SCOPE". Un token de captura no puede pedir otro. Rotar, revocar o borrar tu key lo invalida en el acto.
  • Sus peticiones tienen un límite por captura y por minuto: 15 entre GET …/schema y POST …/context, 30 para POST /process-kpn-emo y 60 para el resto. Por encima responde 429 con reason: "CAPTURE_TOKEN_RATE_LIMIT" y la cabecera Retry-After: no se procesó nada, espera esos segundos y repite. Un token nuevo para el mismo captureId conserva la cuenta. Tu token normal no tiene ese límite. Desde @neurologyca/capture 0.37.0 el SDK espera ese Retry-After y vuelve a enviar la misma petición (como mucho 2 minutos cada vez y 5 veces seguidas), con el aviso transport.rate-limited; cancel no espera. Las versiones anteriores hacen fallar la captura.
  • Para todo lo demás, tu backend sigue usando su token normal.

Hoy solo el Engine del entorno de pruebas tiene esta ruta; el de producción, aún no.

Código Cuándo Cuerpo
401 en /token La key está mal formada, no existe, está revocada o ha caducado, o tu organización está suspendida (la misma respuesta en todos los casos) { "code": 401, "message": "Invalid credentials." }
401 en el resto Falta el token, ha caducado o no es válido, o su key se rotó, se revocó o caducó Cuerpo vacío, con la cabecera WWW-Authenticate: Bearer
429 en /token Demasiadas peticiones de token desde tu IP Cuerpo vacío
  • La key de tu equipo está en Tu cuenta. Revelarla pide tu contraseña, está limitado a 5 veces por hora y queda registrado.
  • El playground nunca pide un token desde el navegador: POST /token y POST /token/capture no pasan por DevLab. Los tokens los pide tu backend.