Scopes and organizations
What a credential may do, who it may do it for, and how a clinic grants you access.
Two things decide whether a call is allowed: the scopes on the credential, and the scopes the organization granted your integration. The API uses the intersection of the two, and never more.
The scope vocabulary
Scopes are resource:verb. There are twenty-six.
| Scope | What it opens |
|---|---|
organization:read | GET /v1/organization, GET /v1/organizations |
catalog:read | Medications, pharmacies, states |
patients:read | Reading patients, exports, case lists by patient |
patients:write | Creating and updating patients, a case's shipping address, deletion requests |
files:read | Reading file metadata |
files:write | Reserving, confirming and deleting files |
consents:read | Reading a patient's consents |
consents:write | Recording a consent |
cases:read | Cases, their events, status history and prescriptions |
cases:write | Filing, cancelling and releasing a case |
messages:read | The message thread on a case |
messages:write | Posting to that thread |
orders:read | Orders raised from an approved case |
labs:read | Lab orders and their released reports, PDF links included, and the panels, collection options and consents an order is confirmed with |
labs:write | Ordering a lab panel for a patient, confirming and cancelling it. Not in the default grant |
visits:read | Reading visits, their slots and a join link |
visits:write | Booking, cancelling and rescheduling a visit. A booking with an intake needs cases:write too |
webhooks:manage | Endpoints, deliveries, redelivery |
events:read | The event feed |
realtime:subscribe | Minting a realtime token |
billing:read | Usage and invoices |
products:read | The storefront's products, their prices and purchase options |
purchases:read | Purchases, customers and memberships |
affiliates:read | Affiliates, their referrals and referred customers, the program, commissions |
affiliates:write | Creating and updating affiliates and their links |
audit:read | Your own integration's audit log for the organization |
test:manage | The sandbox controls, test mode only |
Every operation in the reference names the one scope it requires.
The intersection rule
A credential carries the scopes you ticked when you minted it. A grant carries the scopes the organization approved. The effective set is what both agree on.
A key with cases:write acting for an organization that granted only cases:read may read cases
and nothing more. GET /v1/organization returns the effective set, so you can see what this
credential can actually do here rather than infer it from a refusal.
A call outside the effective set answers 403 forbidden.
Naming the organization
An integration can hold approved grants to several organizations. The credential is the same; the organization is chosen per request.
- One approved grant: it is used automatically and the header is optional.
- More than one: send
Cuvo-Organization: org_…. Without it the request answers400 invalid_request, because guessing would be worse than refusing. - Naming an organization you hold no approved grant to answers
403 forbidden, which is the same answer as naming one that does not exist. - No approved grant at all answers
403 forbidden.
curl https://api.cuvo.co/v1/organizations \
-H "Authorization: Bearer cuvo_sk_test_…"
{
"data": [
{
"id": "org_c8k2q1w9",
"name": "Northgate Health",
"slug": "northgate",
"kind": "DIRECT",
"status": "active",
"scopes": ["organization:read", "patients:write", "cases:write"]
}
],
"has_more": false
}
kind is how the organization reaches Cuvo: DIRECT, RESELLER, RESELLER_CLIENT, or
INTEGRATION for a headless brand that exists only behind an API. It does not change what you can
call. status is active or suspended.
Asking a clinic for access
A grant is requested in the portal, by an integration member with the ADMIN role or above. You need three things:
- The organization's public
org_…id, which the clinic gives you. It is not guessable and cannot be looked up, so an id naming no organization is refused with a clear message rather than turned into a directory. - The scopes you are asking for. Ask for what you need; a request for everything is a slower conversation.
- A note saying who you are and what you are building. The person approving it reads this.
The request appears as a pending grant. Once it is approved, the organization's name appears on your grant and the credential can act for it. Until then the clinic is a bare id on your side, so the form can never become an id-to-name lookup.
None of this blocks you from starting. Every new integration is created with an approved grant on the shared sandbox organization, so the whole loop is reachable before a clinic has heard of you.
Your own workspace's integration
A clinic can also run its own integration, from Settings, API access in its Cuvo workspace, rather than ask a partner to build one. Enabling developer access there creates an integration the workspace owns, with a grant on itself that holds every scope the API had on that day. Nobody else approves it, and keys are minted, rotated and revoked on the same page.
When the API adds a scope later, that grant does not widen by itself. The page lists the new scopes and an Update API scopes button adds them, after a fresh second factor. Keys minted earlier keep the scopes they were minted with, because a key's scopes are fixed when it is minted, so mint a new key to use the new ones. Workspaces that enabled developer access before the commerce and affiliate scopes arrived have already been topped up to them.