Modelo de acceso
Organización, equipos, keys y usuarios finales: qué aísla Engine y dónde DevLab añade sus propios límites.
Dos capas
Sección titulada «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.
| 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
Sección titulada «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). - 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
Sección titulada «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.
Dónde DevLab añade sus propios límites
Sección titulada «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 /tokenno 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
Sección titulada «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.
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
Sección titulada «Errores de DevLab»Dentro de DevLab, además de los errores de Engine (ver Límites), 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
Sección titulada «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) |
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) |
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) |
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) |
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) |
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) |
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
Sección titulada «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 y Keys: rotación, revocación y caducidad.
¿Aún sin cuenta? Solicita acceso.