> ## Documentation Index
> Fetch the complete documentation index at: https://help.elationhealth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Token Scopes

<Note>
  Token scopes are generally available. Practice admins can assign scopes on self-managed credentials from the Elation UI. For credentials that are not self-managed, contact Support to enable token scopes.
</Note>

## 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](/articles/rest/overview/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.

Practice admins can also assign scopes directly to a set of credentials when generating them from the Elation UI. See [Self-service API credential management](/articles/self-service-api-credential-management) for details.

## Scope Format

Scopes follow the pattern:

```sh theme={null}
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 `+`):

```sh theme={null}
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.

<Warning>Scopes **cannot** be combined with the `apiv2` global scope. A token request must use either specific scopes or `apiv2`, not both.</Warning>

## Impersonation Scope

The `act_as_user` scope allows a token to make requests on behalf of a user in your practice. It grants no data access on its own and must be combined with at least one resource scope. See [User Impersonation](/articles/rest/overview/user-impersonation) for details. On self-managed APIv2 credentials, practice admins enable it with the **Allow API Impersonation** checkbox.

## 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 |