# Autenticación

## 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.

```bash
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.

## 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](/docs/es/sdk/backend/).

```js
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
```

## 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](#un-token-para-una-sola-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](/docs/es/api/proxy/).

```js
// 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
}
```

## Caché y renovación

- `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`.

## 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](/docs/es/access/keys/) y el [modelo de acceso](/docs/es/access/model/).

## Scopes

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](/docs/es/access/model/).

## 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](/docs/es/sdk/processing/#la-url-del-token). 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.

## 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

- La key de tu equipo está en [Tu cuenta](/account). 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.
