Keys: rotación, revocación y caducidad
Qué pasa cuando cambia la key de tu equipo y qué hacer en tu backend.
Cuando se rota una key
Sección titulada «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.endy el motivocredential_rotated, y no se puede reabrir con el mismo token.
Cada miembro activo del equipo recibe un correo (nunca lleva la key). Después:
- Revela la key nueva en Tu cuenta.
- Sustitúyela en los secretos de tu backend y despliega.
- Pide un token nuevo con
POST /token. - Reabre, con el token nuevo, los streams de eventos que se cerraron.
Cuando se revoca un equipo
Sección titulada «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
Sección titulada «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
Sección titulada «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 (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
Sección titulada «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
Sección titulada «Qué ve tu backend»POST /token con una key rotada, revocada o caducada (el cuerpo es siempre el mismo):
{ "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:
{ "status": 401, "emptyBody": true, "wwwAuthenticate": "Bearer error=\"invalid_token\"" }Un stream de eventos abierto, tal como termina tras una rotación:
{ "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
Sección titulada «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 (ver Tu cuenta de DevLab); Neurologyca no las revela.
La rotación va en dos pasos, para que tu backend no deje de funcionar:
- Generar valores nuevos (la clave, el secreto o los dos). Se quedan pendientes: el servicio sigue aceptando los actuales.
- 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
Sección titulada «Si se filtra una credencial del procesador»No hay un «rotar ya» de un paso. El procedimiento:
- 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. - El admin de tu organización rota en dos pasos con el procesado aún desactivado: generar, desplegar y activar en Tu cuenta. Mientras tanto el servicio sigue rechazando tus grabaciones, así que los valores filtrados no vuelven a aceptarse.
- Neurologyca lo reactiva, y el servicio vuelve ya con los valores nuevos.
Avisa a Neurologyca en cuanto sospeches una fuga.
En DevLab
Sección titulada «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.