# Access model

## Two layers

**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](/docs/access/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) |

## Who is who

- **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](/docs/access/account/#invite-developers-organization-admin)).
- **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.

## What Engine isolates

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

> A `read_all` key is a data boundary for captures and results, but not for the user directory: any key of the organization lists and edits every end user. If several teams share your organization's users, keep that in mind in your backend.

## Where DevLab adds its own limits

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.

## Deferred processing

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](/docs/access/account/#deferred-processing-credentials).

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.

## Errors from DevLab

Inside DevLab, besides Engine's own errors (see [Limits](/docs/concepts/limits/#errors)), 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 |

## What to do when you see one

| 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](/docs/access/map/#which-message-tells-you-what-is-missing)) |
| `gateway.team_unavailable`, `tenant.team_unavailable` | Your team has no active key: reload, and if it stays so ask Neurologyca ([Your DevLab account](/docs/access/account/#reveal-your-teams-key)) |
| `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](/docs/access/kit/#where-to-find-it)) |
| `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](/docs/start/testing/#the-playground-in-devlab)) |
| `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](#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](/docs/access/account/#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 |

## What each person sees in DevLab

| 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](/docs/access/account/) and [Keys: rotation, revocation and expiry](/docs/access/keys/).

No account yet? [Request access](https://intake.neurologyca.com).
