Ir al contenido
DevLab

Modelo de acceso

Organización, equipos, keys y usuarios finales: qué aísla Engine y dónde DevLab añade sus propios límites.

En esta página
  1. Dos capas
  2. Quién es quién
  3. Qué aísla Engine
  4. Dónde DevLab añade sus propios límites
  5. Procesado en diferido
  6. Errores de DevLab
  7. Qué hacer cuando ves uno
  8. Qué ve cada persona en DevLab

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)
  • 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.

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.

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.

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.

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