Skip to content
DevLab

Access model

Organization, teams, keys and end users: what Engine isolates, and where DevLab adds its own limits.

On this page
  1. Two layers
  2. Who is who
  3. What Engine isolates
  4. Where DevLab adds its own limits
  5. Deferred processing
  6. Errors from DevLab
  7. What to do when you see one
  8. What each person sees in DevLab

Engine is the product: it knows your organization, its API keys and your end users. Everything about Engine on this page also applies when you call it from your own backend.

DevLab is this platform: it gives accounts to the people who integrate, groups them in teams, and keeps each team’s key for you.

Integrating Engine into an application, to use it with people, needs a commercial agreement with Neurologyca first: see Pricing.

Concept Engine DevLab
Organization Your organization in Engine: its catalogue, keys, end users and data The same organization, seen from DevLab
Key A credential with a scope, admin or read_all One key per team, shared by its members
People — Accounts by invitation: team members, the organization admin and Neurologyca
End users The people your application captures; your backend creates them DevLab never creates end users for you (the playground creates its own test users, deleted after 24 hours)
  • Organization admin: the people in your organization’s admin team. Its key has scope admin. In Your integration → Status, the organization admin sees the people of the organization and invites developers to its active teams (see Your DevLab account).
  • Team: people who share one key with scope read_all. A person belongs to one team.
  • End users: the people your application captures. Engine records which key created each one.
  • Neurologyca: creates organizations and teams, invites organization admins (and anyone else), and rotates or revokes keys. Today you ask Neurologyca for these changes, and to remove a person or move them to another team.

DevLab only shows the keys it created for your teams. Your other credentials never appear in DevLab, and DevLab never changes them.

Between organizations, everything. A resource from another organization answers 404, as if it did not exist.

Inside an organization, the scope decides almost everything except the user directory:

Operation admin key read_all key
Create users Yes Yes
List and edit users Any user of the organization Any user of the organization
See a user’s status, enrol or delete Any user of the organization Only the users it created (403 for the others)
Block or unblock Any user of the organization Only the users it created (404 “User not found” for the others, which does not reveal whether they exist)
Capture, read results, interpret, stream events, baseline Any user of the organization Only the users it created (404 for the others)

Deleting a user also needs { "confirm": "<externalId>" } in the body: Engine requires it, for every key.

POST /users/block and POST /users/unblock read their filters (externalId, role, developer) in the query. The test environment’s Engine answers 400 to a call with no filter, unless it sends all=true (every user within the key’s reach: for an admin key, the whole organization), and to a call with a body; the production Engine still ignores the body and, with no filter, acts on every user within reach. Through DevLab, a call without externalId, role or developer is refused with 400 gateway.filter_required, also with all=true. A change of a key’s scope, which Neurologyca makes, applies at once: tokens minted before it are refused and open streams end with stream.end and credential_scope_changed.

Neurologyca provisions one organization in Engine per customer: two customers never share one. A team’s key has scope read_all (the organization admin’s team, admin): used from your backend, a read_all key reaches the data of the end users it created, and lists and edits every end user of the organization.

Inside DevLab’s playground, requests go through DevLab with your session, and DevLab adds:

  • Per team: a team only reaches the end users created with its own key, including the ones your backend created. Anything else answers 403 gateway.not_your_resource. The organization admin’s team reaches the whole organization.
  • Deleting, blocking and unblocking users: only the organization admin.
  • Playground runs: each person deletes their own test runs; the organization admin can delete any run of the organization, for example to free a team that reached its limit.
  • A closed list of routes: POST /token is not available there; your backend mints tokens.
  • No Engine token in the browser: DevLab uses your session and its own copy of your team’s key.

These limits apply only inside DevLab. Your key, used from your backend, follows Engine’s rules above.

In Neurologyca’s processing service, each organization has its own client in it, with one processor key and one webhook secret. Deferred processing is on for a new organization unless Neurologyca turned it off when creating it; Neurologyca turns it on or off, in its admin panel, and DevLab registers or deregisters the client in the service by itself. Your organization’s admin team reveals and rotates the credentials in Your account.

With deferred processing turned off, the service rejects the recordings your own backend sends (the ones in progress finish), and your teams cannot record in Deferred in the DevLab playground either: the same switch decides both, so what your organization does not have turned on you neither try nor use. A recording that was already uploading when it was turned off still finishes and is processed; one still being recorded is rejected when its upload starts. With it on, and in a DevLab environment that has deferred processing, the playground can record any protocol of your team’s catalogue whose kit has a context, and Measurement; in an environment without it, Deferred shows the recorded example. The playground never uses your organization’s client: it records with DevLab’s own processing client.

Inside DevLab, besides Engine’s own errors (see Limits), DevLab can answer with its own codes:

Code Status Meaning
auth.unauthenticated 401 Your DevLab session expired: sign in again
gateway.no_team, tenant.no_team 403 Your account has no team
gateway.team_unavailable, tenant.team_unavailable 403 Your team has no active key
tenant.suspended 403 Your organization is suspended in Engine: none of its keys can call Engine until Neurologyca reactivates it
tenant.deleted 409 Your organization was deleted in Engine (or its deletion is under way): its keys can no longer be revealed or downloaded
gateway.route_not_allowed 403 That route is not available through DevLab
gateway.not_your_resource 403 The resource belongs to another team
gateway.not_found 404 The resource does not exist in your organization
gateway.bad_identifier 400 An id is malformed (in the path or the body), an id that DevLab checks (userProtocolId, user, externalId) comes with another spelling or twice, or a top-level key of the JSON body or the query has characters outside printable ASCII. Values can be any text; only the keys are checked. Engine does not receive the call
gateway.bad_json 400 The body is not JSON
gateway.filter_required 400 POST /users/block or /users/unblock with no filter in the query: it would act on every user within reach
gateway.body_too_large 413 The body is larger than 10 MiB (10,485,760 bytes). The edge in front of DevLab usually rejects it first: then the 413 is an HTML page with no JSON body and no code. You only get gateway.body_too_large when the DevLab server itself rejects the body
engine.rate_limited 503 The token limit (10 per minute) was reached: retry in a minute
engine.upstream_error 502 Engine failed or could not be reached; DevLab does not pass its details on
engine.unreachable 502 Engine could not be reached
engine.timeout 504 Engine took too long to answer
engine.rejected 409 Engine rejected an operation DevLab made for you
tenant.unknown_protocol, tenant.bad_protocol 404, 400 That protocol is not in your catalogue, or its id is malformed
tenant.kit_not_applicable 409 That protocol has no kit: it is the baseline, or it is not in a context
tenant.bad_starter, tenant.body_too_large, tenant.starter_unavailable 400, 413, 503 The starter download is malformed, too large, or not available on this server
tenant.forbidden 403 Only the organization admin sees the people of the organization and invites
tenant.bad_email, tenant.bad_team 400 The invitation’s email or team is malformed
tenant.team_not_found, tenant.team_disabled 404, 409 The team is not one of your active teams, or it was revoked
tenant.account_exists, tenant.account_invited 409 That person already has an account in your organization, or a pending invitation (resend it)
tenant.invitation_not_found 404 There is no pending invitation with that id in your teams
tenant.invite_quota, tenant.resend_quota 429 20 invitations a day per organization; 5 resends an hour per invitation and 20 a day per organization
tenant.busy 429 Another invitation or resend from your organization is being sent: try again in a moment
tenant.invite_unavailable 503 This DevLab does not send email, so it does not invite
uploads.no_client 409 This protocol can’t be recorded in deferred mode
uploads.not_granted 403 Your organization does not have deferred processing turned on, so the playground does not record in Deferred
uploads.unavailable 503 This DevLab has no recording service, or it is not ready right now, so it accepts no uploads
playground.capture_disabled 403 Creating runs is off in this environment
playground.consent_required, playground.bad_consent, playground.consent_not_recorded 409, 400, 503 The playground consent is missing, malformed or could not be recorded
playground.limit 429 10 live runs per team or 30 a day per account; Retry-After says when to retry
playground.enrol_limit 429 The run already has its maximum of enrolments (5 in production; extra.limit says it)
playground.bad_record 400 The recording request is malformed (enrolment, language or transcription switch)
playground.bad_language 400 The narrative language of the live run is not en or es
playground.bad_audience 400 The audience is not in your team’s kit for that protocol (the Audience control of the playground)
playground.audience_busy 409 Changing the audience while a deferred recording of the same person is still being processed: wait for it, or cancel it in Deferred
playground.unknown_protocol 400 That protocol cannot be enrolled here: not in your catalogue, or the baseline
playground.bad_outcome 400 The outcome the playground sends at the end of a session is malformed: a key that is missing or not on the list, a value outside its list or range, an audience outside the kit, more than 10 positions in one enrolment, or more than 1 KB
playground.not_found 404 The run does not exist, is not yours, or was already deleted; when sending the outcome of a session, also if the run is from your previous team or is past its 24 hours
playground.enrol_conflict, playground.enrol_rejected 409 Engine answered 409, or rejected the enrolment (engineStatus); with Engine’s CONTEXT_REQUIRED or CONTEXT_NOT_VALID, also reason (no other value)
playground.not_tenant_admin 403 Only the organization admin sees the runs of the whole organization
news.link_invalid 410 The unsubscribe link is not valid (the same answer whatever the reason)
news.send_all_disabled 403 Sending DevLab updates to everyone is off in this environment
news.send_running 409 Another send of updates is in progress
news.too_many, news.adhoc_quota 400, 429 A one-off send takes at most 20 addresses, and 100 one-off recipients a day in total
news.bad_email 400 An email address of the updates list is malformed
news.confirm_mismatch 400 The update id typed to confirm a send to everyone does not match
news.unknown_entry 404 That update does not exist
legal.terms_required 403 You have not accepted the current DevLab Terms (extra.version names it)
legal.org_terms_required 403 Your organization has not accepted the current DevLab Terms: extra.org is pending (your organization admin has to accept them) or no_admin (your organization has no admin yet)
legal.version, legal.version_stale 400, 409 The terms version sent is not the current one, or it stopped being current while you read it
legal.org_required, legal.not_org_admin 400, 403 As organization admin you also accept on behalf of your organization; only the organization admin can
legal.not_applicable 400 Neurologyca accounts do not accept the customer terms
chat.unavailable 503 The assistant is not available in this DevLab
chat.notice_required 409 Accept the assistant’s notice first
chat.busy, chat.quota 429 Another question of your account is in progress, or a limit was reached (by default 40 questions a day and 10 every 10 minutes per account, plus a daily limit of the assistant itself)
chat.too_long, chat.not_found 400, 404 The question is too long, or the question you rated does not exist
processor.forbidden 403 Only the admin team of your organization manages the processor credentials
processor.disabled 409 Your organization is not registered in the deferred processing service yet (with the option turned off you can still reveal and rotate)
processor.unavailable 503 This DevLab does not offer deferred processing
processor.pending_exists, processor.no_pending 409 There are already pending values (activate or discard them), or there are none to activate
processor.confirm_mismatch 400 The name typed to activate does not match
processor.confirm_in_flight 409 There are recordings in progress (or it could not be known): confirm again to activate the new secret
processor.pending_changed 409 The pending values changed while you were activating or discarding them (another admin replaced them): review them and try again
processor.bad_which, processor.confirm_required 400 The choice of values (current, pending, key, secret or both) is malformed, or the action came without its confirmation
admin.forbidden 403 The admin panel is only for Neurologyca: any other account gets this code
http.cross_site 403 The request did not come from the DevLab page
Code What to do
auth.unauthenticated Your session expired: sign in again
gateway.no_team, tenant.no_team Your account has no team: ask the person who invited you (Where everything is)
gateway.team_unavailable, tenant.team_unavailable Your team has no active key: reload, and if it stays so ask Neurologyca (Your DevLab account)
tenant.suspended Your organization is suspended: rotating or revealing a key does not help. Ask Neurologyca to reactivate it
tenant.deleted Your organization was deleted in Engine: nothing in DevLab brings it back. Ask Neurologyca if you need a new one
http.cross_site Use the DevLab page itself; DevLab refuses requests that come from another site. From your code, call Engine with your key from your backend instead
engine.rate_limited, engine.upstream_error, engine.timeout Wait a minute and retry; if it persists, tell Neurologyca the code
tenant.kit_not_applicable That protocol has no kit (Baseline, or its context is not resolved) (Your kit)
tenant.starter_unavailable Copy the files from the Kit tab; this DevLab does not offer the zip
tenant.invite_unavailable This DevLab does not send email, so it cannot invite: ask Neurologyca
tenant.invite_quota, tenant.resend_quota Wait: 20 invitations a day per organization, 5 resends an hour per invitation and 20 a day per organization
playground.limit If your team has 10 runs alive, delete one of yours (Delete now) or ask your organization admin to delete others of your team. If your account reached its 30 a day, deleting does not help (deleted runs still count): wait for Retry-After (Test your integration)
playground.consent_required Accept the playground consent when the page asks for it
uploads.unavailable This DevLab does not offer recording, or its processing service is not ready right now: the playground keeps the recorded example. Try again later; nothing to fix on your side
uploads.not_granted Your organization does not have deferred processing turned on: Deferred explains what it is and keeps the recorded example. Neurologyca turns it on for your organization, and then it works in the playground and in your integration (Deferred processing)
uploads.no_client This protocol can’t be recorded in deferred mode: its kit has no assigned context, or this environment does not record its context with that language and transcription setting. Choose another protocol (Measurement can always be recorded); Deferred tells you before you press Record
chat.unavailable The assistant is off or not ready in this DevLab: use the documentation search
chat.quota, chat.busy Wait for the current answer to finish, or try again later
chat.notice_required Accept the assistant’s notice, which the panel shows before the first question
news.link_invalid The unsubscribe link is not valid: use the one in the latest email, or ignore it
legal.terms_required Accept the DevLab Terms in the dialog DevLab shows, or sign in again (Terms and your agreements)
legal.org_terms_required With pending, ask your organization admin to sign in and accept the terms for your organization; with no_admin, ask Neurologyca to give your organization an admin
legal.version, legal.version_stale Reload the page and accept the version it shows
Person Documentation Your account Your integration Reveal a key Deferred processing Admin panel
No account When the documentation is public Sign-in page Sign-in page — — —
Team member Yes Your team’s key The catalogue of your organization, the protocol viewer, the kit and the status of your integration Yours The service URL and IP No
Member of a revoked team Yes Your profile and your team, shown as revoked, with no key A notice, your team’s DevLab milestones and your organization’s protocols in read-only mode, without the kit — — No
Organization admin Yes Every key of your organization, including the admin key The catalogue, the kit and the status of the whole organization, with its people and invitations Any of them The URL and IP, and the processor key and webhook secret: reveal and rotate No
Neurologyca Yes Every key Any organization’s catalogue and status, read-only, from the admin panel Any Turns it on or off per organization and sees its status; never the key or the secret Yes

See Your DevLab account and Keys: rotation, revocation and expiry.

No account yet? Request access.