# Modelo de acceso

## Dos capas

**Engine** es el producto: conoce tu **organización**, sus **API keys** y tus **usuarios finales**. Todo lo que esta página cuenta de Engine vale también cuando lo llamas desde tu propio backend.

**DevLab** es esta plataforma: da **cuentas** a las personas que integran, las agrupa en **equipos** y te guarda la key de cada equipo.

Integrar Engine en una aplicación, para usarla con personas, exige antes un acuerdo comercial con Neurologyca: mira [Precios](/docs/es/access/pricing/).

| Concepto | Engine | DevLab |
| --- | --- | --- |
| Organización | Tu organización en Engine: su catálogo, keys, usuarios finales y datos | La misma organización, vista desde DevLab |
| Key | Una credencial con un scope, `admin` o `read_all` | Una key por equipo, compartida por sus miembros |
| Personas | — | Cuentas por invitación: miembros de equipo, el admin de la organización y Neurologyca |
| Usuarios finales | Las personas que captura tu aplicación; los crea tu backend | DevLab nunca crea usuarios finales por ti (el playground crea sus propios usuarios de prueba, que se borran a las 24 horas) |

## Quién es quién

- **Admin de la organización**: las personas del equipo admin de tu organización. Su key tiene scope `admin`. En **Tu integración → Estado**, el admin de la organización ve las personas de la organización e invita developers a sus equipos activos (ver [Tu cuenta de DevLab](/docs/es/access/account/#invitar-developers-admin-de-la-organización)).
- **Equipo**: personas que comparten una key con scope `read_all`. Cada persona pertenece a un equipo.
- **Usuarios finales**: las personas que captura tu aplicación. Engine registra qué key creó cada uno.
- **Neurologyca**: crea organizaciones y equipos, invita a los admins de la organización (y a cualquiera), y rota o revoca keys. Hoy esos cambios se piden a Neurologyca, y también retirar a una persona o cambiarla de equipo.

DevLab solo muestra las keys que creó para tus equipos. Tus otras credenciales nunca aparecen en DevLab y DevLab nunca las cambia.

## Qué aísla Engine

**Entre organizaciones, todo.** Un recurso de otra organización responde `404`, como si no existiera.

**Dentro de una organización, el scope lo decide casi todo salvo el directorio de usuarios:**

| Operación | Key `admin` | Key `read_all` |
| --- | --- | --- |
| Crear usuarios | Sí | Sí |
| Listar y editar usuarios | Cualquier usuario de la organización | Cualquier usuario de la organización |
| Ver el estado de un usuario, inscribir o borrar | Cualquier usuario de la organización | Solo los usuarios que creó (`403` con los demás) |
| Bloquear o desbloquear | Cualquier usuario de la organización | Solo los usuarios que creó (`404` "User not found" con los demás, que no revela si existen) |
| Capturar, leer resultados, interpretar, recibir eventos, baseline | Cualquier usuario de la organización | Solo los usuarios que creó (`404` con los demás) |

Borrar un usuario exige además `{ "confirm": "<externalId>" }` en el cuerpo: lo exige Engine, con cualquier key.

`POST /users/block` y `POST /users/unblock` leen sus filtros (`externalId`, `role`, `developer`) **en la query**. El Engine del entorno de pruebas responde `400` a una llamada sin filtro, salvo que lleve `all=true` (todos los usuarios al alcance de la key: con una key `admin`, toda la organización), y a una llamada con cuerpo; el Engine de producción aún ignora el cuerpo y, sin filtro, actúa sobre todos los usuarios al alcance. A través de DevLab, una llamada sin `externalId`, `role` ni `developer` se rechaza con `400 gateway.filter_required`, también con `all=true`. Un cambio de scope de una key, que hace Neurologyca, se aplica al momento: los tokens acuñados antes se rechazan y los streams abiertos terminan con `stream.end` y `credential_scope_changed`.

Neurologyca da de alta **una organización en Engine por cliente**: dos clientes nunca comparten una. La key de un equipo tiene scope `read_all` (la del equipo del admin de la organización, `admin`): usada desde tu backend, una key `read_all` alcanza los datos de los usuarios finales que creó, y lista y edita a todos los usuarios finales de la organización.

> Una key `read_all` es una frontera de datos para las capturas y los resultados, pero no para el directorio de usuarios: cualquier key de la organización lista y edita a todos los usuarios finales. Si varios equipos comparten los usuarios de tu organización, tenlo en cuenta en tu backend.

## Dónde DevLab añade sus propios límites

En el playground de DevLab, las peticiones pasan por DevLab con tu sesión, y DevLab añade:

- **Por equipo:** un equipo solo alcanza los usuarios finales creados con su propia key, también los que creó tu backend. Lo demás responde `403 gateway.not_your_resource`. El equipo del admin de la organización alcanza toda la organización.
- **Borrar, bloquear y desbloquear** usuarios: solo el admin de la organización.
- **Ejecuciones del playground:** cada persona borra las suyas; el admin de la organización puede borrar cualquiera de la organización, por ejemplo para liberar a un equipo que llegó a su límite.
- **Una lista cerrada de rutas:** `POST /token` no está disponible ahí; los tokens los pide tu backend.
- **Ningún token de Engine en el navegador:** DevLab usa tu sesión y su propia copia de la key de tu equipo.

Estos límites solo se aplican dentro de DevLab. Tu key, usada desde tu backend, sigue las reglas de Engine de arriba.

## Procesado en diferido

En el servicio de procesado de Neurologyca, cada organización tiene su propio cliente en él, con una clave del procesador y un secreto de webhook. El diferido está activado en una organización nueva salvo que Neurologyca lo desactivara al crearla; Neurologyca lo activa o desactiva, en su panel de admin, y DevLab da de alta o de baja el cliente en el servicio por sí solo. El equipo admin de tu organización revela y rota las credenciales en [Tu cuenta](/docs/es/access/account/#credenciales-del-procesado-en-diferido).

Con el procesado en diferido desactivado, el servicio rechaza las grabaciones que envíe tu propio backend (las que están en curso terminan), y **tus equipos tampoco pueden grabar en Diferido en el playground de DevLab**: el mismo interruptor decide las dos cosas, así que lo que tu organización no tiene activado ni lo pruebas ni lo usas. Una grabación que ya se estaba subiendo al desactivarlo termina y se procesa; una que aún se está grabando se rechaza al empezar su subida. Con él activado, y en un entorno de DevLab que tenga el procesado en diferido, el playground puede grabar cualquier protocolo del catálogo de tu equipo cuyo kit tenga un contexto, y Measurement; en un entorno sin él, Diferido enseña el ejemplo grabado. El playground nunca usa el cliente de tu organización: graba con el cliente de procesado propio de DevLab.

## Errores de DevLab

Dentro de DevLab, además de los errores de Engine (ver [Límites](/docs/es/concepts/limits/#errores)), DevLab puede responder con sus propios códigos:

| Código | Estado | Qué significa |
| --- | --- | --- |
| `auth.unauthenticated` | `401` | Tu sesión de DevLab caducó: vuelve a iniciar sesión |
| `gateway.no_team`, `tenant.no_team` | `403` | Tu cuenta no tiene equipo |
| `gateway.team_unavailable`, `tenant.team_unavailable` | `403` | Tu equipo no tiene una key activa |
| `tenant.suspended` | `403` | Tu organización está suspendida en Engine: ninguna de sus keys puede llamar a Engine hasta que Neurologyca la reactive |
| `tenant.deleted` | `409` | Tu organización se ha borrado en Engine (o su borrado está en curso): ya no se pueden revelar ni descargar sus keys |
| `gateway.route_not_allowed` | `403` | Esa ruta no está disponible a través de DevLab |
| `gateway.not_your_resource` | `403` | El recurso es de otro equipo |
| `gateway.not_found` | `404` | El recurso no existe en tu organización |
| `gateway.bad_identifier` | `400` | Un id está mal formado (en la ruta o en el cuerpo), un id que DevLab comprueba (`userProtocolId`, `user`, `externalId`) llega con otra grafía o dos veces, o una clave de primer nivel del cuerpo JSON o de la query tiene caracteres fuera de ASCII imprimible. Los valores pueden ser cualquier texto; solo se miran las claves. Engine no recibe la llamada |
| `gateway.bad_json` | `400` | El cuerpo no es JSON |
| `gateway.filter_required` | `400` | `POST /users/block` o `/users/unblock` sin ningún filtro en la query: afectaría a todos los usuarios al alcance |
| `gateway.body_too_large` | `413` | El cuerpo pasa de 10 MiB (10.485.760 bytes). Lo normal es que lo rechace antes el borde que hay delante de DevLab: entonces el `413` es una página HTML, sin cuerpo JSON y sin `code`. Solo recibes `gateway.body_too_large` cuando lo rechaza el propio servidor de DevLab |
| `engine.rate_limited` | `503` | Se llegó al límite de tokens (10 por minuto): reintenta en un minuto |
| `engine.upstream_error` | `502` | Engine falló o no respondió; DevLab no reenvía sus detalles |
| `engine.unreachable` | `502` | No se pudo llegar a Engine |
| `engine.timeout` | `504` | Engine tardó demasiado en responder |
| `engine.rejected` | `409` | Engine rechazó una operación que DevLab hizo por ti |
| `tenant.unknown_protocol`, `tenant.bad_protocol` | `404`, `400` | Ese protocolo no está en tu catálogo, o su id está mal formado |
| `tenant.kit_not_applicable` | `409` | Ese protocolo no tiene kit: es el baseline, o no está en un contexto |
| `tenant.bad_starter`, `tenant.body_too_large`, `tenant.starter_unavailable` | `400`, `413`, `503` | La descarga del starter está mal formada, es demasiado grande o no está disponible en este servidor |
| `tenant.forbidden` | `403` | Solo el admin de la organización ve las personas de la organización e invita |
| `tenant.bad_email`, `tenant.bad_team` | `400` | El email o el equipo de la invitación están mal formados |
| `tenant.team_not_found`, `tenant.team_disabled` | `404`, `409` | El equipo no es uno de tus equipos activos, o se revocó |
| `tenant.account_exists`, `tenant.account_invited` | `409` | Esa persona ya tiene cuenta en tu organización, o una invitación pendiente (reenvíala) |
| `tenant.invitation_not_found` | `404` | No hay ninguna invitación pendiente con ese id en tus equipos |
| `tenant.invite_quota`, `tenant.resend_quota` | `429` | 20 invitaciones al día por organización; 5 reenvíos por hora por invitación y 20 al día por organización |
| `tenant.busy` | `429` | Se está enviando otra invitación o reenvío de tu organización: inténtalo de nuevo en un momento |
| `tenant.invite_unavailable` | `503` | Este DevLab no envía correo, así que no invita |
| `uploads.no_client` | `409` | No se puede grabar este protocolo en diferido |
| `uploads.not_granted` | `403` | Tu organización no tiene activado el procesado en diferido, así que el playground no graba en Diferido |
| `uploads.unavailable` | `503` | Este DevLab no tiene servicio de grabación, o no está listo ahora mismo, así que no acepta subidas |
| `playground.capture_disabled` | `403` | Crear ejecuciones está apagado en este entorno |
| `playground.consent_required`, `playground.bad_consent`, `playground.consent_not_recorded` | `409`, `400`, `503` | Falta el consentimiento del playground, está mal formado o no se pudo registrar |
| `playground.limit` | `429` | 10 ejecuciones vivas por equipo o 30 al día por cuenta; `Retry-After` dice cuándo reintentar |
| `playground.enrol_limit` | `429` | La ejecución ya tiene su máximo de inscripciones (5 en producción; lo dice `extra.limit`) |
| `playground.bad_record` | `400` | La petición de grabación está mal formada (inscripción, idioma o interruptor de transcripción) |
| `playground.bad_language` | `400` | El idioma de la narrativa de la ejecución en vivo no es `en` ni `es` |
| `playground.bad_audience` | `400` | La audiencia no está en el kit de tu equipo para ese protocolo (el mando Audiencia del playground) |
| `playground.audience_busy` | `409` | Cambiar la audiencia mientras una grabación en diferido de la misma persona sigue procesándose: espera a que acabe o cancélala en Diferido |
| `playground.unknown_protocol` | `400` | Ese protocolo no se puede inscribir aquí: no está en tu catálogo, o es el baseline |
| `playground.bad_outcome` | `400` | El resultado que el playground envía al acabar una sesión está mal formado: falta una clave o sobra una que no está en la lista, un valor está fuera de su lista o de su rango, la audiencia no está en el kit, la inscripción ya tiene 10 posiciones o pasa de 1 KB |
| `playground.not_found` | `404` | La ejecución no existe, no es tuya o ya se borró; al enviar el resultado de una sesión, también si es de tu equipo anterior o ya pasó sus 24 horas |
| `playground.enrol_conflict`, `playground.enrol_rejected` | `409` | Engine respondió `409`, o rechazó la inscripción (`engineStatus`); con `CONTEXT_REQUIRED` o `CONTEXT_NOT_VALID` de Engine, también `reason` (ningún otro valor) |
| `playground.not_tenant_admin` | `403` | Solo el admin de la organización ve las ejecuciones de toda la organización |
| `news.link_invalid` | `410` | El enlace de baja no es válido (la misma respuesta sea cual sea el motivo) |
| `news.send_all_disabled` | `403` | El envío de las novedades de DevLab a todos está apagado en este entorno |
| `news.send_running` | `409` | Hay otro envío de novedades en curso |
| `news.too_many`, `news.adhoc_quota` | `400`, `429` | Un envío puntual admite 20 direcciones como máximo, y 100 destinatarios puntuales al día en total |
| `news.bad_email` | `400` | Una dirección de correo de la lista de novedades está mal formada |
| `news.confirm_mismatch` | `400` | El id de la novedad tecleado para confirmar un envío a todos no coincide |
| `news.unknown_entry` | `404` | Esa novedad no existe |
| `legal.terms_required` | `403` | No has aceptado los Términos de DevLab vigentes (`extra.version` dice cuáles) |
| `legal.org_terms_required` | `403` | Tu organización no ha aceptado los Términos de DevLab vigentes: `extra.org` es `pending` (los tiene que aceptar la persona admin de tu organización) o `no_admin` (tu organización aún no tiene admin) |
| `legal.version`, `legal.version_stale` | `400`, `409` | La versión de los términos enviada no es la vigente, o dejó de serlo mientras la leías |
| `legal.org_required`, `legal.not_org_admin` | `400`, `403` | Como admin de la organización aceptas también en nombre de tu organización; solo puede hacerlo el admin de la organización |
| `legal.not_applicable` | `400` | Las cuentas de Neurologyca no aceptan los términos de cliente |
| `chat.unavailable` | `503` | El asistente no está disponible en este DevLab |
| `chat.notice_required` | `409` | Acepta antes el aviso del asistente |
| `chat.busy`, `chat.quota` | `429` | Hay otra pregunta de tu cuenta en curso, o se alcanzó un límite (por defecto, 40 preguntas al día y 10 cada 10 minutos por cuenta, y además un límite diario del propio asistente) |
| `chat.too_long`, `chat.not_found` | `400`, `404` | La pregunta es demasiado larga, o la pregunta que valoras no existe |
| `processor.forbidden` | `403` | Solo el equipo de administración de tu organización gestiona las credenciales del procesador |
| `processor.disabled` | `409` | Tu organización aún no está dada de alta en el servicio de procesado en diferido (con la opción desactivada se puede revelar y rotar igualmente) |
| `processor.unavailable` | `503` | Este DevLab no ofrece el procesado en diferido |
| `processor.pending_exists`, `processor.no_pending` | `409` | Ya hay valores pendientes (actívalos o descártalos), o no hay ninguno que activar |
| `processor.confirm_mismatch` | `400` | El nombre tecleado para activar no coincide |
| `processor.confirm_in_flight` | `409` | Hay grabaciones en curso (o no se pudo saber): confirma de nuevo para activar el secreto nuevo |
| `processor.pending_changed` | `409` | Los valores pendientes cambiaron mientras activabas o descartabas (otro admin los sustituyó): revísalos y vuelve a intentarlo |
| `processor.bad_which`, `processor.confirm_required` | `400` | La elección de valores (`current`, `pending`, `key`, `secret` o `both`) está mal formada, o la acción llegó sin su confirmación |
| `admin.forbidden` | `403` | El panel de administración es solo de Neurologyca: cualquier otra cuenta recibe este código |
| `http.cross_site` | `403` | La petición no salió de la página de DevLab |

## Qué hacer cuando ves uno

| Código | Qué hacer |
| --- | --- |
| `auth.unauthenticated` | Tu sesión caducó: entra de nuevo |
| `gateway.no_team`, `tenant.no_team` | Tu cuenta no tiene equipo: pregunta a quien te invitó ([Dónde está cada cosa](/docs/es/access/map/#qué-mensaje-te-dice-qué-falta)) |
| `gateway.team_unavailable`, `tenant.team_unavailable` | Tu equipo no tiene key activa: recarga, y si sigue igual pídeselo a Neurologyca ([Tu cuenta de DevLab](/docs/es/access/account/#revela-la-key-de-tu-equipo)) |
| `tenant.suspended` | Tu organización está suspendida: rotar o revelar una key no lo arregla. Pide a Neurologyca que la reactive |
| `tenant.deleted` | Tu organización está borrada en Engine: nada en DevLab la recupera. Si necesitas una nueva, pídesela a Neurologyca |
| `http.cross_site` | Usa la propia página de DevLab; DevLab rechaza las peticiones que vienen de otro sitio. Desde tu código, llama a Engine con tu key desde tu backend |
| `engine.rate_limited`, `engine.upstream_error`, `engine.timeout` | Espera un minuto y reintenta; si persiste, dile el código a Neurologyca |
| `tenant.kit_not_applicable` | Ese protocolo no tiene kit (Baseline, o su contexto no está resuelto) ([Tu kit](/docs/es/access/kit/#dónde-encontrarlo)) |
| `tenant.starter_unavailable` | Copia los ficheros de la pestaña Kit; este DevLab no ofrece el zip |
| `tenant.invite_unavailable` | Este DevLab no envía correo, así que no puede invitar: pídeselo a Neurologyca |
| `tenant.invite_quota`, `tenant.resend_quota` | Espera: 20 invitaciones al día por organización, 5 reenvíos por hora y por invitación y 20 al día por organización |
| `playground.limit` | Si tu equipo tiene 10 ejecuciones vivas, borra una tuya (**Borrar ahora**) o pide al admin de tu organización que borre otras de tu equipo. Si tu cuenta llegó a las 30 al día, borrar no ayuda (las borradas también cuentan): espera según `Retry-After` ([Probar tu integración](/docs/es/start/testing/#el-playground-en-devlab)) |
| `playground.consent_required` | Acepta el consentimiento del playground cuando la página te lo pida |
| `uploads.unavailable` | Este DevLab no ofrece grabación, o su servicio de procesado no está listo ahora mismo: el playground conserva el ejemplo grabado. Prueba más tarde; no hay nada que arreglar por tu parte |
| `uploads.not_granted` | Tu organización no tiene activado el procesado en diferido: Diferido explica qué es y conserva el ejemplo grabado. Lo activa Neurologyca para tu organización, y entonces sirve en el playground y en tu integración ([Procesado en diferido](#procesado-en-diferido)) |
| `uploads.no_client` | No se puede grabar este protocolo en diferido: su kit no tiene un contexto asignado, o este entorno no graba su contexto con ese idioma y esa transcripción. Elige otro protocolo (Measurement siempre se puede grabar); Diferido te lo dice antes de pulsar **Grabar** |
| `chat.unavailable` | El asistente está apagado o no está listo en este DevLab: usa el buscador de la doc |
| `chat.quota`, `chat.busy` | Espera a que termine la respuesta en curso, o inténtalo más tarde |
| `chat.notice_required` | Acepta el aviso del asistente, que el panel enseña antes de la primera pregunta |
| `news.link_invalid` | El enlace de baja no es válido: usa el del último correo, o ignóralo |
| `legal.terms_required` | Acepta los Términos de DevLab en el diálogo que enseña DevLab, o vuelve a iniciar sesión ([Los términos y tus acuerdos](/docs/es/access/account/#los-términos-y-tus-acuerdos)) |
| `legal.org_terms_required` | Con `pending`, pide a la persona admin de tu organización que entre y acepte los términos por tu organización; con `no_admin`, pide a Neurologyca que dé un admin a tu organización |
| `legal.version`, `legal.version_stale` | Recarga la página y acepta la versión que enseña |

## Qué ve cada persona en DevLab

| Persona | Documentación | Tu cuenta | Tu integración | Revelar una key | Procesado en diferido | Panel de admin |
| --- | --- | --- | --- | --- | --- | --- |
| Sin cuenta | Cuando la documentación es pública | Página de inicio de sesión | Página de inicio de sesión | — | — | — |
| Miembro de un equipo | Sí | La key de tu equipo | El catálogo de tu organización, el visualizador de protocolos, el kit y el estado de tu integración | La tuya | La URL y la IP del servicio | No |
| Miembro de un equipo revocado | Sí | Tu perfil y tu equipo, como revocado, sin key | Un aviso, los hitos de DevLab de tu equipo y los protocolos de tu organización en solo lectura, sin kit | — | — | No |
| Admin de la organización | Sí | Todas las keys de tu organización, también la key admin | El catálogo, el kit y el estado de toda la organización, con sus personas e invitaciones | Cualquiera de ellas | La URL y la IP, y la clave del procesador y el secreto de webhook: revelar y rotar | No |
| Neurologyca | Sí | Todas las keys | El catálogo y el estado de cualquier organización, en solo lectura, desde el panel de admin | Cualquiera | Lo activa o lo desactiva por organización y ve su estado; nunca la clave ni el secreto | Sí |

Ver [Tu cuenta de DevLab](/docs/es/access/account/) y [Keys: rotación, revocación y caducidad](/docs/es/access/keys/).

¿Aún sin cuenta? [Solicita acceso](https://intake.neurologyca.com).
