Sharing & permissions

Orders are owned by the organization that created them. To let someone else view or edit an order, you share it, individually by email, or via a public share link.

Owners, invited users, and link holders

• Owner organization, the org whose API key created the order. Full access. Orders are always billed to the owner, regardless of who else has access or who unlocks exports.
• Invited user, a Relu user account that's been given explicit access to this order.
• Link holder, anyone who holds a public share link URL.

What invited users and link holders can do also depends on the owner organization's standing, not on their own. An invited user whose own account still needs a payment method can open, finalize and recompute an order shared with them. If the owner organization cannot have orders submitted or results opened, invited users and link holders get 403 with detail.code set to order_owner_refused until the owner resolves it.

Roles

Every invited user and every share link has a role that sets the baseline access:

Permissions

On top of the role baseline, you can grant or revoke specific permissions:

• order:approve
• order:unlock:implant_planning
• order:export:implant_planning (plus :report, :guides sub-scopes)
• order:download
• order:change_permissions

Permissions are additive (granted_permissions) or subtractive (revoked_permissions). This lets you compose access precisely, e.g., "editor who can't unlock exports" or "viewer who can download".

See Share an order for API examples.

Effective permissions on order responses

Order responses (GET /orders/{id}, GET /orders) include a permissions array listing the resolved permissions for whoever is making the request — owner, invited user, or share-link holder. Use it instead of computing access yourself from role plus granted_permissions / revoked_permissions.

{
  "id": "...",
  "permissions": ["order:read", "order:edit", "order:approve", "order:download"]
}

Use this to gate UI affordances ("show the Approve button only when order:approve is in the array") rather than re-deriving the matrix client-side.

Share links

Share links are URLs that grant access to anyone who has the URL. Each link has:

• A role (same options as invited users)
• Optional expiry (expires_at)
• Optional extra permissions (granted_permissions)
• A unique token that works until you revoke or expire it

Links are useful when you don't know the recipient's email in advance, e.g., a referring dentist sending a case to a lab.

The token can travel two ways:

• In the URL as ?key=<token> — what the standard viewer URL uses.
• As X-Share-Key: <token> header — for programmatic access from a custom UI.

A share-link holder is scoped to that order only. Endpoints that normally need authentication (e.g. GET /services/{id} to fetch the parameter schema for the viewer) accept the share-link token, but only for the service used by the shared order — cross-service requests return 404. Treat 404 from a share-linked endpoint as an out-of-scope request, not an auth error.

Revocation

All sharing is revocable. Deleting an invited user or a share link takes effect immediately.

API surface

See the API reference for the full set of sharing endpoints, and Share an order for walkthroughs with code examples.