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

# Scopes

> Permission scopes that control which API endpoints your app can access

Scopes are permissions that control which API endpoints your app can access. When a clinic installs your app, they grant the scopes your app has requested.

## How Scopes Work

1. When you **create your app**, you declare which scopes it needs
2. When a **clinic installs** your app, they review and approve those scopes
3. When you **create an API key**, you select which of the approved scopes it should have
4. At runtime, your effective permissions are the intersection of the key's scopes and the clinic's installation grants, and each API endpoint **checks** for the required scope before returning data

If you call an endpoint without the required scope, you'll receive a **403 Forbidden** response.

## Available Scopes

### Read Scopes

#### Patient Data

| Scope           | Endpoints               | Description                              |
| --------------- | ----------------------- | ---------------------------------------- |
| `read:patients` | `GET /v3/patients`      | List patients with search and pagination |
|                 | `GET /v3/patients/{id}` | Get a specific patient by ID             |

#### Appointments

| Scope               | Endpoints                   | Description                      |
| ------------------- | --------------------------- | -------------------------------- |
| `read:appointments` | `GET /v3/appointments`      | List appointments with filters   |
|                     | `GET /v3/appointments/{id}` | Get a specific appointment by ID |

#### Providers

| Scope            | Endpoints                | Description                   |
| ---------------- | ------------------------ | ----------------------------- |
| `read:providers` | `GET /v3/providers`      | List providers                |
|                  | `GET /v3/providers/{id}` | Get a specific provider by ID |

#### Facilities

| Scope             | Endpoints                 | Description                   |
| ----------------- | ------------------------- | ----------------------------- |
| `read:facilities` | `GET /v3/facilities`      | List facilities               |
|                   | `GET /v3/facilities/{id}` | Get a specific facility by ID |

#### Billing

| Scope             | Endpoints            | Description                                         |
| ----------------- | -------------------- | --------------------------------------------------- |
| `read:bills`      | `GET /v3/bills`      | List bills with pagination                          |
|                   | `GET /v3/bills/{id}` | Get detailed bill with line items and coding groups |
| `read:encounters` | *(legacy)*           | Same as `read:bills`                                |

#### Claims

| Scope         | Endpoints             | Description                            |
| ------------- | --------------------- | -------------------------------------- |
| `read:claims` | `GET /v3/claims`      | List claims with pagination            |
|               | `GET /v3/claims/{id}` | Get detailed claim with insurance info |

#### Notes

| Scope             | Endpoints                            | Description                                           |
| ----------------- | ------------------------------------ | ----------------------------------------------------- |
| `read:notes`      | `GET /v3/notes`                      | List patient visit notes                              |
|                   | `GET /v3/notes/{id}`                 | Get a specific note by ID                             |
| `read:soap_notes` | `GET /v3/notes?includeSoapNote=true` | Include SOAP note content (requires `read:notes` too) |

#### Tasks

| Scope        | Endpoints            | Description                                                           |
| ------------ | -------------------- | --------------------------------------------------------------------- |
| `read:tasks` | `GET /v3/tasks`      | List tasks with filters (status, note, provider, patient, date range) |
|              | `GET /v3/tasks/{id}` | Get a specific task by ID                                             |

#### Emails

| Scope         | Endpoints             | Description                |
| ------------- | --------------------- | -------------------------- |
| `read:emails` | `GET /v3/emails`      | List emails                |
|               | `GET /v3/emails/{id}` | Get a specific email by ID |

#### Phone Numbers

| Scope                | Endpoints               | Description               |
| -------------------- | ----------------------- | ------------------------- |
| `read:phone_numbers` | `GET /v3/phone-numbers` | List clinic phone numbers |

#### Inventory

| Scope            | Endpoints                                 | Description                          |
| ---------------- | ----------------------------------------- | ------------------------------------ |
| `read:inventory` | `GET /v3/inventory/changes`               | List inventory changes               |
|                  | `GET /v3/inventory/changes/{id}`          | Get a specific inventory change      |
|                  | `GET /v3/inventory/changes/{id}/products` | Get products for an inventory change |
|                  | `GET /v3/inventory/stock-levels`          | Get current stock levels             |
| `read:products`  | `GET /v3/inventory/products`              | List products in the catalog         |
|                  | `GET /v3/inventory/products/{id}`         | Get a specific product               |

### Write Scopes

#### Notes

| Scope                | Endpoints                                                         | Description                           |
| -------------------- | ----------------------------------------------------------------- | ------------------------------------- |
| `write:notes_images` | `POST /v3/notes/{noteId}/images?providerId=`                      | Upload an image to a note             |
|                      | `DELETE /v3/notes/{noteId}/images/{imageId}?providerId=`          | Delete an image from a note           |
| `write:soap_notes`   | `PATCH /v3/notes/{noteId}?providerId=`                            | Edit SOAP note fields (with EHR sync) |
|                      | `PATCH /v3/notes/{noteId}/impressions/{impressionId}?providerId=` | Edit impression fields (ModMed only)  |

#### Tasks

| Scope         | Endpoints              | Description                          |
| ------------- | ---------------------- | ------------------------------------ |
| `write:tasks` | `POST /v3/tasks`       | Create a task (synchronous EHR push) |
|               | `PATCH /v3/tasks/{id}` | Update task status (complete/cancel) |

#### Emails

| Scope          | Endpoints              | Description   |
| -------------- | ---------------------- | ------------- |
| `write:emails` | `POST /v3/emails/send` | Send an email |

#### Products

| Scope            | Endpoints                         | Description                |
| ---------------- | --------------------------------- | -------------------------- |
| `write:products` | `POST /v3/inventory/products`     | Create a new product       |
|                  | `PUT /v3/inventory/products/{id}` | Update an existing product |

#### Inventory

| Scope             | Endpoints                    | Description                |
| ----------------- | ---------------------------- | -------------------------- |
| `write:inventory` | `POST /v3/inventory/changes` | Create an inventory change |

## Checking Your Scopes

Use the `/v3/marketplace/me` endpoint to see which scopes your API key currently has. This endpoint does not require any scope — it is always available.

```bash theme={null}
curl -X GET "https://api.maxcare.ai/v3/marketplace/me" \
  -H "Authorization: Bearer max_prd_ak_SBA...01S" \
  -H "X-Organization-Id: 7e2c8cfe-b7a9-4deb-986d-e7012589e72b"
```

The response includes your granted scopes:

```json theme={null}
{
  "code": "success",
  "data": {
    "app": {
      "id": "app_2b6fe6754b674990bb07fa16ece694c3",
      "slug": "testapi",
      "liveVersionId": "apv_89ba6db5e6644a008849299672992970"
    },
    "organization": {
      "id": "org_7e2c8cfeb7a94deb986de7012589e72b"
    },
    "scopes": [
      "read:patients",
      "read:appointments",
      "read:providers",
      "read:facilities",
      "read:bills",
      "read:claims",
      "read:notes",
      "read:soap_notes",
      "read:emails",
      "read:phone_numbers",
      "read:inventory",
      "read:products",
      "read:encounters",
      "write:notes_images",
      "write:emails",
      "write:products",
      "write:inventory"
    ]
  }
}
```

## Insufficient Scope Error

If you call an endpoint without the required scope:

```json theme={null}
{
  "code": "forbidden",
  "message": "Insufficient scope. Required: read:patients",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

To resolve this, update your app's requested scopes in the Max AI dashboard and have the clinic re-approve the updated permissions.