Scopes

Scopes limit what an API key can do. Apply the principle of least privilege: only grant the scopes each integration needs. The API reference lists the authentication requirements for each endpoint.

How scopes are named

Scopes follow a verb:resource pattern (e.g. read:orders, create:input-files). Verbs are one of read, create, update, delete.

Available scopes

Orders

• create:orders
• read:orders — read order info and download input/output files
• update:orders
• delete:orders

Inbox cases

• create:inbox-cases: register and commit Inbox files, validate source metadata, and create cases
• read:inbox-cases: list and read cases, download case files, and preview file-to-order mapping
• update:inbox-cases: edit cases and change their files or classifications
• delete:inbox-cases: delete cases or case files

The Inbox intake quickstart only needs create:inbox-cases. Add read:inbox-cases if the sender reads the accepted case. Creating an order from a case also needs create:orders.

Input files

• create:input-files
• read:input-files
• update:input-files
• delete:input-files

Output files

• create:output-files
• read:output-files
• update:output-files
• delete:output-files

Order permissions (sharing)

• read:order-permissions
• create:order-permissions
• update:order-permissions
• delete:order-permissions

Order comments

• create:comments
• read:comments
• update:comments
• delete:comments

Presets

• read:presets
• create:presets
• update:presets
• delete:presets

Roles

• read:roles

Users

• read:users
• update:users

Implant library

• read:implant-library

Organization

• read:organization-logo — fetch your organization's logo (e.g. to preview the logo embedded in surgical-report / patient-passport PDFs). This is a narrow, logo-only read; the logo endpoint also accepts the broader read:organizations, so grant whichever your integration already has.

Account consolidation (Relu admins only)

• admin:read:organizations — read any organization's members, case counts and billing status
• admin:consolidate:organizations — move every user and preset of one organization into another

These two, and admin:assume:users below, are the only admin rights a key can carry. These two are only on an account consolidation key: made by a signed-in Relu admin with the "Account consolidation only" option. Such a key carries these two scopes and nothing else, acts as its maker, must expire within a year, and stops after 60 days unused. A key can never empty a Paddle-linked organization or move people into a partner's own organization.

The key stops working once its maker is no longer a Relu admin. That is checked against Auth0 and the answer is kept for up to 5 minutes per server process, so removing someone's admin role stops their keys within 5 minutes, not instantly. Deleting the key stops it at once.

Every move made with the key is recorded in Automate's audit log under the admin who made it, not under the person who asked for the move. The Relu Sales platform, which holds the key, records which of its users asked and why, and puts that in the move's reason.

Assume users (Relu admins only)

• admin:assume:users — start sessions that act as one user for at most an hour

This right is only on an assume-users key: made by a signed-in Relu admin with the "Assume users only" option, on the same terms as an account consolidation key (this scope and nothing else, acts as its maker, expires within a year, stops after 60 days unused, stops within 5 minutes of its maker losing admin). The key opens two routes and nothing else:

• POST /connections/assumed-user-session — assume_user_email, expires_delta (at most 3600 seconds, never past the key's own expiry), reason, optional scopes to narrow the session. Returns the session key.
• POST /connections/assumed-user-session/end — token: ends a session this key's maker started.

A session acts as the user and can do whatever that user can: its rights are the user's own, read from Auth0 when the session starts, and never an admin right. A blocked user, or one whose rights Auth0 cannot confirm, gets no session. Its own access ends with its hour: it cannot make an API key, a desktop machine login or enrollment token, or a provisioned connection, cannot open the automation builder, the support chat or a socket, and cannot reach /connections at all. What the user could do that lasts on its own, such as inviting a member, creating an automation or sharing an order, a session can do too. Automate's audit log records the user it acted as and the admin who made the key; the reason becomes the session key's name.

No session acts as an Automate admin, as anyone holding a staff-only right such as read:translation-suggestions, or as anyone with a @relu.ai or @relu.eu address. A key's maker can start at most 10 sessions an hour and 30 a day, ended sessions included (429 past that). Every start is written to the log as assumed_user_session started and posted to the risk alert Slack channel; refusals are logged as assumed_user_session refused.

Refunds and feedback

• create:refunds — submit feedback and refund requests
• read:refunds — list your feedback and refund history

Scopes for end-user (assumed-user) tokens

When you mint a user token on behalf of an end user, only a subset of scopes is allowed — roughly the order/file/comment/permission operations, plus read:users, read:roles, read:implant-library, and the preset scopes. A user token is always limited to certain orders, so it reaches only those orders and its user's own account, whatever its scopes. See the user-tokens page for the full allow-list and what a user token reaches.