---
title: 'Scopes'
description: 'SMART on FHIR scope reference for the Huli Public API v1.'
nav: 'Auth'
order: 10
version: v1
source: generated
updated: '2026-09-23'
---
# Scopes
This page is hand-curated from the OpenAPI spec. Treat it as the authoritative reference — it matches the scopes advertised in the `/fhir/.well-known/smart-configuration` endpoint.
Scopes follow the SMART on FHIR `system/.` format. Request only the scopes your integration requires.
## Permission letters
- **r** — read a single resource by ID
- **s** — search (query with parameters, paginated Bundle response)
- **c** — create a new resource
- **u** — update an existing resource
- **d** — delete a resource
## Scope reference
### Patient
#### system/Patient.rs
**Read and search patients**
Allows reading individual Patient records by ID and searching the patient list. Does not permit creating or modifying patient data.
Permissions granted: **r** — read a single resource by ID, **s** — search (query with parameters, paginated Bundle response)
#### system/Patient.cru
**Create, read, and update patients**
Allows creating new Patient records, reading existing ones, and updating demographic or contact information. Includes all operations of `system/Patient.rs`.
Permissions granted: **c** — create a new resource, **r** — read a single resource by ID, **u** — update an existing resource
### Appointment
#### system/Appointment.rs
**Read and search appointments**
Allows reading individual Appointment resources and searching the appointment list by patient, practitioner, date, or status.
Permissions granted: **r** — read a single resource by ID, **s** — search (query with parameters, paginated Bundle response)
#### system/Appointment.cru
**Create, read, and update appointments**
Allows booking new appointments, reading existing ones, and updating appointment status (e.g. cancellation). Includes all operations of `system/Appointment.rs`.
Permissions granted: **c** — create a new resource, **r** — read a single resource by ID, **u** — update an existing resource
### Encounter
#### system/Encounter.rs
**Read and search encounters**
Allows reading individual Encounter records (clinical consultations) and searching by patient, date, status, or class.
Permissions granted: **r** — read a single resource by ID, **s** — search (query with parameters, paginated Bundle response)
#### system/Encounter.cru
**Create, read, and update encounters**
Allows creating new Encounter records, reading existing ones, and updating encounter status or details. Includes all operations of `system/Encounter.rs`.
Permissions granted: **c** — create a new resource, **r** — read a single resource by ID, **u** — update an existing resource
### Observation
#### system/Observation.rs
**Read and search observations**
Allows reading individual Observation resources (vital signs, lab results, exam findings) and searching by patient, encounter, LOINC code, date, status, or category.
Permissions granted: **r** — read a single resource by ID, **s** — search (query with parameters, paginated Bundle response)
#### system/Observation.cru
**Create, read, and update observations**
Allows recording new Observation values, reading existing ones, and amending previously recorded observations. LOINC codes are validated on write.
Permissions granted: **c** — create a new resource, **r** — read a single resource by ID, **u** — update an existing resource
### MedicationRequest
#### system/MedicationRequest.rs
**Read and search medication requests**
Allows reading individual MedicationRequest resources (prescription orders) and searching by patient or encounter.
Permissions granted: **r** — read a single resource by ID, **s** — search (query with parameters, paginated Bundle response)
#### system/MedicationRequest.c
**Create medication requests**
Allows creating MedicationRequest resources (each auto-links to a draft prescription).
Permissions granted: **c** — create a new resource
#### system/MedicationRequest.cru
**Create, read, and update medication requests**
Allows creating, reading, and updating MedicationRequest resources. Updates are read-then-merge and preserve app-only fields; a signed or cancelled prescription cannot be modified.
Permissions granted: **c** — create a new resource, **r** — read a single resource by ID, **u** — update an existing resource
### ServiceRequest
#### system/ServiceRequest.rs
**Read and search service requests**
Allows reading individual ServiceRequest resources (study / procedure orders) and searching by patient or encounter.
Permissions granted: **r** — read a single resource by ID, **s** — search (query with parameters, paginated Bundle response)
#### system/ServiceRequest.c
**Create service requests**
Allows creating ServiceRequest resources (a single-item order).
Permissions granted: **c** — create a new resource
#### system/ServiceRequest.cru
**Create, read, and update service requests**
Allows creating, reading, and updating ServiceRequest resources. Updates are read-then-merge on draft orders and preserve app-only fields; a signed or cancelled order cannot be modified, and multi-item orders are read-only.
Permissions granted: **c** — create a new resource, **r** — read a single resource by ID, **u** — update an existing resource
### Composition
#### system/Composition.rs
**Read and search clinical notes**
Allows reading individual Composition resources (the clinical-note projection of an encounter) and searching by patient, date, or type.
Permissions granted: **r** — read a single resource by ID, **s** — search (query with parameters, paginated Bundle response)
#### system/Composition.cru
**Create, read, and update clinical notes**
Allows creating Composition resources, reading existing ones, and updating the clinical narrative (with optimistic concurrency via If-Match). Includes all operations of `system/Composition.rs`.
Permissions granted: **c** — create a new resource, **r** — read a single resource by ID, **u** — update an existing resource
### DocumentReference
#### system/DocumentReference.rs
**Read and search document references**
Allows reading individual DocumentReference resources (lab results, imaging, scanned files; the binary is served via a 30-minute signed URL) and searching by patient, category, type, or date.
Permissions granted: **r** — read a single resource by ID, **s** — search (query with parameters, paginated Bundle response)
#### system/DocumentReference.cru
**Create, read, and update document references**
Allows uploading document binaries ($upload — base64 inline or multipart, 25 MB ceiling), reading existing ones, and updating their metadata. Includes all operations of `system/DocumentReference.rs`.
Permissions granted: **c** — create a new resource, **r** — read a single resource by ID, **u** — update an existing resource
### Practitioner
#### system/Practitioner.rs
**Read practitioners**
Allows reading individual Practitioner resources (healthcare providers). Practitioner data is read-only in the public API.
Permissions granted: **r** — read a single resource by ID, **s** — search (query with parameters, paginated Bundle response)
### Organization
#### system/Organization.rs
**Read organization**
Allows reading the Organization resource that corresponds to your API key organization. Organization data is read-only in the public API.
Permissions granted: **r** — read a single resource by ID, **s** — search (query with parameters, paginated Bundle response)
### Subscription
#### system/Subscription.rs
**Read and search webhook subscriptions**
Allows reading a webhook Subscription by ID and listing the subscriptions registered for your API key organization.
Permissions granted: **r** — read a single resource by ID, **s** — search (query with parameters, paginated Bundle response)
#### system/Subscription.crud
**Manage webhook subscriptions**
Allows creating, reading, updating, and deleting outbound-webhook Subscriptions. Requires a signed BAA on the API key. Includes all operations of `system/Subscription.rs`.
Permissions granted: **c** — create a new resource, **r** — read a single resource by ID, **u** — update an existing resource, **d** — delete a resource
## Requesting scopes
Include the `scope` parameter in your token request. Separate multiple scopes with spaces:
```bash
curl -X POST https://api.huli.ai/auth/token \
-d "grant_type=client_credentials" \
-d "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
-d "client_assertion=${CLIENT_ASSERTION}" \
-d "scope=system/Patient.rs system/Appointment.rs"
```
If `scope` is omitted, all scopes registered for the API key are granted. The issued token includes the granted scopes in the `scope` response field.