Beta Feature: Token scopes are currently in closed beta and available to select customers only.

Overview

Token scopes allow you to restrict an access token's permissions to only the API resources it needs. When requesting a token via the Get Token endpoint, you can specify one or more scopes using the scope parameter.

If no scope is specified, the token defaults to the apiv2 global scope, which grants access to all API resources.

Scope Format

Scopes follow the pattern:

system/<resource>.<permission>

resource: The API resource name (e.g., patients, allergies, lab_orders).
permission: Either read or write.

Permissions

read grants access to the resource's GET endpoints.
write grants access to the resource's POST, PUT, PATCH, and DELETE endpoints.

Nested resources

Nested endpoints are controlled by their parent resource's scope. For example, system/patients.read and system/patients.write control access to the patient insurance card image endpoint at /api/2.0/patients/{patient_id}/policies/{policy_id}/card-images.

Visit note and document signing are governed by a separate opt-in mechanism, but are permissioned under system/visit_notes.write.

Requesting Scopes

Pass a space-separated list of scopes in the scope parameter when requesting a token. Because the body is application/x-www-form-urlencoded, spaces between scopes must be URL-encoded (typically as %20 or +):

POST /api/2.0/oauth2/token/
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&scope=system/patients.read%20system/allergies.read%20system/allergies.write

Combining Scopes

Scopes can be combined to grant a token access to multiple resources. For example, a token with system/patients.read system/medications.read system/medications.write can read patients and both read and write medications.

⚠️
Scopes cannot be combined with the apiv2 global scope. A token request must use either specific scopes or apiv2, not both.

Available Scopes

Patient Profile API

Scope	Description
`system/allergies.read`	Read access to allergies
`system/allergies.write`	Write access to allergies
`system/allergy_documentation.read`	Read access to allergy documentation (NKDA)
`system/allergy_documentation.write`	Write access to allergy documentation (NKDA)
`system/drug_intolerances.read`	Read access to drug intolerances
`system/drug_intolerances.write`	Write access to drug intolerances
`system/family_histories.read`	Read access to family histories
`system/family_histories.write`	Write access to family histories
`system/histories.read`	Read access to histories
`system/histories.write`	Write access to histories
`system/immunizations.read`	Read access to immunizations
`system/immunizations.write`	Write access to immunizations
`system/patients.read`	Read access to patients
`system/patients.write`	Write access to patients
`system/patient-provider-team-members.read`	Read access to provider team members
`system/patient-provider-team-members.write`	Write access to provider team members
`system/problems.read`	Read access to problems
`system/problems.write`	Write access to problems
`system/vaccine.read`	Read access to vaccines
`system/vaccine.write`	Write access to vaccines

Patient Document API

Scope	Description
`system/ccda.read`	Read access to C-CDA documents
`system/ccda.write`	Write access to C-CDA documents
`system/clinical_documents.read`	Read access to clinical documents
`system/clinical_documents.write`	Write access to clinical documents
`system/discontinued_medications.read`	Read access to discontinued medications
`system/discontinued_medications.write`	Write access to discontinued medications
`system/document_tags.read`	Read access to document tags
`system/document_tags.write`	Write access to document tags
`system/incoming_files.read`	Read access to incoming files
`system/incoming_files.write`	Write access to incoming files
`system/injections.read`	Read access to injections
`system/injections.write`	Write access to injections
`system/letters.read`	Read access to letters
`system/letters.write`	Write access to letters
`system/medication_history_download_fills.read`	Read access to medication history download fills
`system/medication_history_download_fills.write`	Write access to medication history download fills
`system/medication_history_downloads.read`	Read access to medication history downloads
`system/medication_history_downloads.write`	Write access to medication history downloads
`system/medication_refills.read`	Read access to medication refills
`system/medication_refills.write`	Write access to medication refills
`system/medications.read`	Read access to medications
`system/medications.write`	Write access to medications
`system/non_visit_notes.read`	Read access to non-visit notes
`system/non_visit_notes.write`	Write access to non-visit notes
`system/patient_form_requests.read`	Read access to patient form requests
`system/patient_form_requests.write`	Write access to patient form requests
`system/patient_form_submissions.read`	Read access to patient form submissions
`system/patient_form_submissions.write`	Write access to patient form submissions
`system/patient_forms.read`	Read access to patient forms
`system/patient_forms.write`	Write access to patient forms
`system/report_types.read`	Read access to report types
`system/report_types.write`	Write access to report types
`system/reports.read`	Read access to reports
`system/reports.write`	Write access to reports
`system/visit_note_templates.read`	Read access to visit note templates
`system/visit_note_templates.write`	Write access to visit note templates
`system/visit_note_types.read`	Read access to visit note types
`system/visit_note_types.write`	Write access to visit note types
`system/visit_notes.read`	Read access to visit notes
`system/visit_notes.write`	Write access to visit notes
`system/vitals.read`	Read access to vitals
`system/vitals.write`	Write access to vitals

Orders API

Scope	Description
`system/ancillary_companies.read`	Read access to ancillary companies
`system/ancillary_companies.write`	Write access to ancillary companies
`system/cardiac_centers.read`	Read access to cardiac centers
`system/cardiac_centers.write`	Write access to cardiac centers
`system/cardiac_order_tests.read`	Read access to cardiac order tests
`system/cardiac_order_tests.write`	Write access to cardiac order tests
`system/cardiac_orders.read`	Read access to cardiac orders
`system/cardiac_orders.write`	Write access to cardiac orders
`system/imaging_centers.read`	Read access to imaging centers
`system/imaging_centers.write`	Write access to imaging centers
`system/imaging_order_tests.read`	Read access to imaging order tests
`system/imaging_order_tests.write`	Write access to imaging order tests
`system/imaging_orders.read`	Read access to imaging orders
`system/imaging_orders.write`	Write access to imaging orders
`system/lab_facility_identifiers.read`	Read access to lab facility identifiers
`system/lab_facility_identifiers.write`	Write access to lab facility identifiers
`system/lab_order_compendiums.read`	Read access to lab order compendiums
`system/lab_order_compendiums.write`	Write access to lab order compendiums
`system/lab_order_sets.read`	Read access to lab order sets
`system/lab_order_sets.write`	Write access to lab order sets
`system/lab_order_tests.read`	Read access to lab order tests
`system/lab_order_tests.write`	Write access to lab order tests
`system/lab_orders.read`	Read access to lab orders
`system/lab_orders.write`	Write access to lab orders
`system/lab_vendor_integrations.read`	Read access to lab vendor integrations
`system/lab_vendor_integrations.write`	Write access to lab vendor integrations
`system/lab_vendor_patient_sites.read`	Read access to lab vendor patient sites
`system/lab_vendor_patient_sites.write`	Write access to lab vendor patient sites
`system/lab_vendors.read`	Read access to lab vendors
`system/lab_vendors.write`	Write access to lab vendors
`system/pulmonary_centers.read`	Read access to pulmonary centers
`system/pulmonary_centers.write`	Write access to pulmonary centers
`system/pulmonary_order_tests.read`	Read access to pulmonary order tests
`system/pulmonary_order_tests.write`	Write access to pulmonary order tests
`system/pulmonary_orders.read`	Read access to pulmonary orders
`system/pulmonary_orders.write`	Write access to pulmonary orders
`system/sleep_centers.read`	Read access to sleep centers
`system/sleep_centers.write`	Write access to sleep centers
`system/sleep_order_tests.read`	Read access to sleep order tests
`system/sleep_order_tests.write`	Write access to sleep order tests
`system/sleep_orders.read`	Read access to sleep orders
`system/sleep_orders.write`	Write access to sleep orders

Messaging API

Scope	Description
`system/message_threads.read`	Read access to message threads
`system/message_threads.write`	Write access to message threads
`system/thread_members.read`	Read access to thread members
`system/thread_members.write`	Write access to thread members
`system/thread_messages.read`	Read access to thread messages
`system/thread_messages.write`	Write access to thread messages

Scheduling API

Scope	Description
`system/appointment_types.read`	Read access to appointment types
`system/appointment_types.write`	Write access to appointment types
`system/appointments.read`	Read access to appointments
`system/appointments.write`	Write access to appointments
`system/recurring_event_groups.read`	Read access to recurring event groups
`system/recurring_event_groups.write`	Write access to recurring event groups

Insurance API

Scope	Description
`system/insurance_companies.read`	Read access to insurance companies
`system/insurance_companies.write`	Write access to insurance companies
`system/insurance_plans.read`	Read access to insurance plans
`system/insurance_plans.write`	Write access to insurance plans

Billing API

Scope	Description
`system/billing_codes.read`	Read access to billing codes
`system/billing_codes.write`	Write access to billing codes
`system/bills.read`	Read access to bills
`system/bills.write`	Write access to bills

Practice API

Scope	Description
`system/contacts.read`	Read access to contacts
`system/contacts.write`	Write access to contacts
`system/delegate_permissions.read`	Read access to delegate permissions
`system/delegate_permissions.write`	Write access to delegate permissions
`system/handouts.read`	Read access to handouts
`system/handouts.write`	Write access to handouts
`system/medication_order_templates.read`	Read access to medication order templates
`system/medication_order_templates.write`	Write access to medication order templates
`system/office_staff.read`	Read access to office staff
`system/office_staff.write`	Write access to office staff
`system/physicians.read`	Read access to physicians
`system/physicians.write`	Write access to physicians
`system/practice_medications.read`	Read access to practice medications
`system/practice_medications.write`	Write access to practice medications
`system/practices.read`	Read access to practices
`system/practices.write`	Write access to practices
`system/print_headers.read`	Read access to print headers
`system/print_headers.write`	Write access to print headers
`system/service_locations.read`	Read access to service locations
`system/service_locations.write`	Write access to service locations
`system/staff_groups.read`	Read access to staff groups
`system/staff_groups.write`	Write access to staff groups

Reference Data API

These resources are constant values provided for reference purposes and cannot be updated. They are all read-only.

Scope	Description
`system/languages.read`	Read access to languages
`system/packaged_medication_labelers.read`	Read access to packaged medication labelers
`system/packaged_medications.read`	Read access to packaged medications
`system/pharmacies.read`	Read access to pharmacies
`system/reference_medications.read`	Read access to reference medications