# Keys: rotación, revocación y caducidad

## Cuando se rota una key

Neurologyca rota una key cuando alguien que la conocía deja el equipo, cuando puede haberse filtrado o antes de que caduque. La rotación es **inmediata**:

- la key anterior deja de emitir tokens;
- un token emitido con ella se rechaza en la siguiente petición;
- un stream de eventos abierto termina con `stream.end` y el motivo `credential_rotated`, y no se puede reabrir con el mismo token.

Cada miembro activo del equipo recibe un correo (nunca lleva la key). Después:

1. Revela la key nueva en [Tu cuenta](/account).
2. Sustitúyela en los secretos de tu backend y despliega.
3. Pide un token nuevo con `POST /token`.
4. Reabre, con el token nuevo, los streams de eventos que se cerraron.

> Trata el `401` una vez: cuando Engine rechace un token que creías válido, pide uno nuevo y reintenta la petición una sola vez.

## Cuando se revoca un equipo

Su key deja de funcionar para siempre y el equipo se desactiva en DevLab: los tokens emitidos con ella se rechazan y los streams abiertos terminan con `credential_revoked`. Revocar retira la key, no a las personas: sus miembros conservan la cuenta y pueden seguir entrando, pero no ven ninguna key; en Tu integración ven sus hitos y los protocolos de su organización en solo lectura, sin kit. Para retirar el acceso a alguien, Neurologyca desactiva su cuenta (ver abajo). Hoy revocar no envía ningún correo.

## Cuando alguien deja el equipo

Neurologyca desactiva su cuenta y sus sesiones terminan en el acto. Una key que haya copiado sigue funcionando hasta que la key se **rota**: pide a Neurologyca que la rote.

## Caducidad

Las keys creadas a través de DevLab caducan **un año** después de crearse o de su última rotación. DevLab muestra la fecha de caducidad en [Tu cuenta](/account) (**Comprobar**, un clic por key) y, al admin de la organización, en Tu integración → Estado (por equipo). Cuando quedan menos de 30 días, la fecha lleva "\< 30 días" (y, para la key de tu propio equipo, Tu cuenta te avisa): pide a Neurologyca una rotación antes. Pasada la fecha, la key aparece como **Caducada**. Una key caducada se comporta como una revocada (`credential_expired`); rotarla renueva el año.

## Si tu organización está suspendida

Mientras Neurologyca tenga tu organización suspendida en Engine, ninguna de sus keys funciona: el `POST /token` de tu backend recibe el mismo `401` que con una key equivocada, y DevLab (tu cuenta, el kit y el playground) dice **Suspendido** y responde `403 tenant.suspended`. Rotar una key no lo arregla. No se borra nada: cuando Neurologyca la reactiva, las mismas keys vuelven a funcionar. Si la organización se ha dado de baja, revelar o descargar una key responde `409 tenant.deleted`.

## Qué ve tu backend

`POST /token` con una key rotada, revocada o caducada (el cuerpo es siempre el mismo):

```json
{ "status": 401, "body": { "code": 401, "message": "Invalid credentials." } }
```

Cualquier otra petición con un token emitido con esa key: `401`, cuerpo vacío y esta cabecera:

```json
{ "status": 401, "emptyBody": true, "wwwAuthenticate": "Bearer error=\"invalid_token\"" }
```

Un stream de eventos abierto, tal como termina tras una rotación:

```json
{ "events": ["connected", "stream.end"], "reason": "credential_rotated" }
```

Solo tras `idle_timeout` puedes reabrir un stream con el mismo token; tras un motivo `credential_*`, pide uno nuevo. Lo mismo pasa cuando Neurologyca cambia el scope de una key: se aplica al momento, los tokens acuñados antes se rechazan y los streams abiertos terminan con `credential_scope_changed`.

## Credenciales del procesado en diferido

Si tu organización usa el servicio de procesado de Neurologyca para el modo diferido, tiene dos credenciales más, aparte de las keys de Engine: la **clave del procesador**, que tu backend presenta al servicio, y el **secreto de webhook**, con el que el servicio firma sus avisos. Hay una pareja por organización y la comparten todos los equipos: la usa el backend de cada equipo, y cada equipo activo recibe la pareja actual en su starter de grabación con **Incluir mi key y las credenciales del procesador**. Solo el equipo admin de tu organización las revela y las rota, en [Tu cuenta](/account) (ver [Tu cuenta de DevLab](/docs/es/access/account/#credenciales-del-procesado-en-diferido)); Neurologyca no las revela.

La rotación va en **dos pasos**, para que tu backend no deje de funcionar:

1. **Generar valores nuevos** (la clave, el secreto o los dos). Se quedan pendientes: el servicio sigue aceptando los actuales.
2. Despliégalos en el backend de cada equipo que use el diferido y pulsa **Activar** enseguida. DevLab se los envía al servicio en segundos; hasta que los confirma, el servicio acepta los anteriores.

Rotar **solo la clave** no tiene ventana de riesgo: las grabaciones en curso ya no la usan, y un envío que el servicio rechaza lo reintenta tu backend. Rotar el **secreto** sí: los avisos de las grabaciones en curso se firman con el secreto nuevo en cuanto activas, y un aviso que un backend rechaza por firma no se reintenta: se pierde, y solo `getJob().webhook.status` lo enseña. Por eso Activar te dice cuántas hay en curso y te pide que confirmes que el backend de cada equipo ya tiene el secreto nuevo. Para cerrar esa ventana, un backend puede aceptar los dos secretos mientras dura: `createWebhookHandler` y `createProcessorTokenHandler` reciben un solo `secret`, así que monta una segunda instancia con el secreto anterior: copia la petición antes de que la lea la primera (`const copy = req.clone()`) y pásale la copia a la segunda solo cuando la primera responde 401. Quítala cuando los valores nuevos estén activos.

El servicio publica también la IP desde la que te llama. Limita tus tres rutas a ella como defensa en profundidad: **la IP no autentica**. Verificar la firma es obligatorio, y el SDK lo hace por ti.

### Si se filtra una credencial del procesador

No hay un «rotar ya» de un paso. El procedimiento:

1. **Neurologyca desactiva el procesado en diferido** de tu organización en su panel de admin. El servicio rechaza desde ese momento las grabaciones que envíe tu backend con `403 E_CLIENT_DISABLED` (las que están en curso terminan). Tus equipos tampoco pueden grabar en Diferido en el playground de DevLab hasta que se reactive.
2. El admin de tu organización **rota en dos pasos** con el procesado aún desactivado: generar, desplegar y activar en [Tu cuenta](/account). Mientras tanto el servicio sigue rechazando tus grabaciones, así que los valores filtrados no vuelven a aceptarse.
3. **Neurologyca lo reactiva**, y el servicio vuelve ya con los valores nuevos.

Avisa a Neurologyca en cuanto sospeches una fuga.

## En DevLab

Dentro de DevLab, tu siguiente petición usa la key nueva. Un stream de eventos abierto termina con `credential_rotated`, igual que en tu backend.

Si una key que DevLab te guarda se rota o se revoca fuera de DevLab, DevLab ya no puede usarla, y el playground responde `403 gateway.team_unavailable`. Pide a Neurologyca que rote o revoque esas keys.
