Autenticación
Cambia tu API key por un token de vida corta, en tu servidor.
API key y token
Sección titulada «API key y token»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.
curl -s -X POST "$ENGINE/token" \ -H "Content-Type: application/json" \ -d '{"apiKey":"<your-api-key>"}'{ "token": "<jwt>", "expiresIn": 3600 }expiresIn va en segundos. Léelo de la respuesta en vez de dar un valor por hecho.
Con el SDK: ningún token en el navegador
Sección titulada «Con el SDK: ningún token en el navegador»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.
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áginaLa key, solo en tu servidor
Sección titulada «La key, solo en tu servidor»- 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 elAuthorizationde sus propias llamadas a Engine, detrás de tu propia autenticación; nunca se lo entregues a la página. Ver Proxy a mano.
// 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}Caché y renovación
Sección titulada «Caché y renovación»POST /tokentiene 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.
Rotación y revocación
Sección titulada «Rotación y revocación»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.
Un token para una sola captura
Sección titulada «Un token para una sola captura»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:
{ "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}/schemayGET /stream/{userProtocolId}. EnPOST …/contextyPOST …/cancelpuedes omitircaptureId: se usa el del token.POST /process-kpn-emotiene que llevarlo, así que pasa al SDK el mismocaptureId. Con él, el stream solo trae los eventos de esa mecánica y se cierra constream.endyreason: "token_expired"cuando el token caduca. - Cualquier otra ruta, mecánica o captura,
POST /analyzeincluida, responde403conreason: "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 …/schemayPOST …/context, 30 paraPOST /process-kpn-emoy 60 para el resto. Por encima responde429conreason: "CAPTURE_TOKEN_RATE_LIMIT"y la cabeceraRetry-After: no se procesó nada, espera esos segundos y repite. Un token nuevo para el mismocaptureIdconserva la cuenta. Tu token normal no tiene ese límite. Desde@neurologyca/capture0.37.0 el SDK espera eseRetry-Aftery vuelve a enviar la misma petición (como mucho 2 minutos cada vez y 5 veces seguidas), con el avisotransport.rate-limited;cancelno 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.
Errores
Sección titulada «Errores»| 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 |
En DevLab
Sección titulada «En DevLab»- 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 /tokenyPOST /token/captureno pasan por DevLab. Los tokens los pide tu backend.