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

# Permissions

> Complete reference of API key permissions and their associated endpoints

# Permissions

Every RxScale API key carries a set of permissions that control which endpoints the key can access. This page provides a complete reference of all available permissions, grouped by API.

## How Permissions Work

When you create an API key, you assign it one or more permissions. Each API endpoint requires a specific permission -- if the key lacks that permission, the request returns `403 Permission Denied`.

```bash theme={null}
# A key with only `orders_read` can list orders...
curl -X GET "https://api.rxscale.com/v1/external_pharmacy_api/pharmacy_orders/" \
  -H "X-API-Key: your-api-key-here"

# ...but cannot update order status (requires `orders_write`)
curl -X PATCH "https://api.rxscale.com/v1/external_pharmacy_api/pharmacy_orders/{uid}/status" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"status": "in-progress"}'
# Returns 403: Permission denied
```

<Note>
  Permissions are set during API key creation. Contact your RxScale account manager to add or change permissions on an existing key.
</Note>

## External Pharmacy API

The External Pharmacy API uses pharmacy-specific API keys. Permissions are simple string identifiers checked at runtime.

| Permission           | Type  | Endpoints                                                               |
| -------------------- | ----- | ----------------------------------------------------------------------- |
| `orders_read`        | Read  | `GET /pharmacy_orders/` -- List pharmacy orders                         |
|                      |       | `GET /pharmacy_orders/{uid}` -- Get order details                       |
| `orders_write`       | Write | `PATCH /pharmacy_orders/{uid}/status` -- Update order status            |
|                      |       | `PATCH /pharmacy_orders/{uid}/complete_order` -- Complete order         |
| `stock_read`         | Read  | `GET /pharmacy_skus/` -- List pharmacy SKUs                             |
| `stock_write`        | Write | `PATCH /pharmacy_skus/{uid}/stock` -- Update stock level                |
| `pharmacy_sku_write` | Write | `PATCH /pharmacy_skus/{uid}` -- Update SKU (price, stock, external\_id) |
|                      |       | `PATCH /pharmacy_skus/{uid}/stock` -- Update stock level                |
|                      |       | `PATCH /pharmacy_skus/{uid}/external_id` -- Update external ID          |
| `webhooks_read`      | Read  | `GET /webhooks/` -- List webhook subscriptions                          |
| `webhooks_write`     | Write | `POST /webhooks/` -- Register a webhook                                 |
|                      |       | `DELETE /webhooks/{uid}` -- Remove a webhook                            |

<Info>
  The `PATCH /pharmacy_skus/{uid}/stock` endpoint accepts either `stock_write` or `pharmacy_sku_write`. If your key has either permission, the request succeeds. All other SKU write endpoints require `pharmacy_sku_write` specifically.
</Info>

## Management API

The Management API uses organisation-scoped API keys. Permissions follow a `resource:action` naming convention and are enforced via the `@require_api_key_permission` decorator.

| Permission                            | Type  | Endpoints                                                                                                        |
| ------------------------------------- | ----- | ---------------------------------------------------------------------------------------------------------------- |
| `order:read`                          | Read  | `GET /orders/{uid}` -- Get order details                                                                         |
| `prescription:read`                   | Read  | `GET /prescriptions/{uid}` -- Get prescription details                                                           |
|                                       |       | Unlocks prescription data within order responses (when combined with `order:read`)                               |
| `prescription:external_sign`          | Write | `POST /prescriptions/{uid}/render` -- Trigger asynchronous PDF rendering                                         |
|                                       |       | `POST /prescriptions/{uid}/external-sign` -- Mark a prescription as `EXTERNALLY_SIGNED` and dispatch to pharmacy |
| `product:read`                        | Read  | `GET /products/` -- List products with connected SKU and shop data                                               |
| `doctor:read`                         | Read  | `GET /doctors/` -- List doctors                                                                                  |
| `doctor_statistics:read`              | Read  | `GET /doctors/{uid}/statistics` -- Get prescription statistics for a doctor                                      |
| `patient:read`                        | Read  | `GET /patients/?email={email}` -- Look up a patient by email                                                     |
|                                       |       | `GET /patients/{uid}` -- Get patient details                                                                     |
|                                       |       | `GET /patients/{uid}/intent/{intent}` -- Get intent return code                                                  |
| `waiting_room:read`                   | Read  | `GET /waiting-room/{uid}/status` -- Get queue entry status                                                       |
| `waiting_room:write`                  | Write | `POST /waiting-room/register` -- Register a patient in the waiting room                                          |
|                                       |       | `DELETE /waiting-room/{uid}` -- Cancel a queue registration                                                      |
| `wallet_pass_template:read`           | Read  | `GET /wallet-passes/templates` -- List wallet pass templates                                                     |
| `wallet_pass:read`                    | Read  | `GET /wallet-passes/` -- List wallet passes                                                                      |
| `wallet_pass_push_notification:write` | Write | `POST /wallet-passes/push-notifications` -- Send push notifications                                              |
| `notification_subscription:read`      | Read  | `GET /notification-subscriptions/` -- List webhook subscriptions                                                 |
| `notification_subscription:write`     | Write | `POST /notification-subscriptions/` -- Create a webhook subscription                                             |
|                                       |       | `DELETE /notification-subscriptions/` -- Remove a webhook subscription                                           |
|                                       |       | `POST /notification-subscriptions/test` -- Send a test webhook                                                   |

<Warning>
  When an API key has `order:read` but not `prescription:read`, order responses will have their prescription data stripped. Add `prescription:read` to include full prescription details within order data.
</Warning>

### Notification Subscriptions

The notification subscription endpoints (`/notification-subscriptions/`) on the Management API require the granular `notification_subscription` permissions. Listing subscriptions requires `notification_subscription:read`; creating, removing, and sending test webhooks require `notification_subscription:write`.

| Endpoint                           | Method   | Description                   | Permission                        |
| ---------------------------------- | -------- | ----------------------------- | --------------------------------- |
| `/notification-subscriptions/`     | `GET`    | List webhook subscriptions    | `notification_subscription:read`  |
| `/notification-subscriptions/`     | `POST`   | Create a webhook subscription | `notification_subscription:write` |
| `/notification-subscriptions/`     | `DELETE` | Remove a webhook subscription | `notification_subscription:write` |
| `/notification-subscriptions/test` | `POST`   | Send a test webhook           | `notification_subscription:write` |

<Note>
  Keys created before these permissions were introduced must have `notification_subscription:read` / `notification_subscription:write` added before they can call these endpoints again. Contact your RxScale account manager to update an existing key.
</Note>

## Public API

The Public API uses organisation-scoped API keys (with optional legacy `X-RxScale-Authorization` header support). It is designed for telemedicine providers to query products and create checkouts.

| Permission                     | Type  | Endpoints                                                                                         |
| ------------------------------ | ----- | ------------------------------------------------------------------------------------------------- |
| `product:read`                 | Read  | `GET /products/{shop_identifier}` -- List products for a shop                                     |
|                                |       | `POST /products/{shop_identifier}/live-stock` -- Check product stock availability before checkout |
| `order:read`                   | Read  | `GET /orders/{shop_identifier}` -- Query order status by prescription UIDs                        |
| `create_prescription_checkout` | Write | `POST /prescriptions/{shop_identifier}` -- Create a prescription-based checkout                   |
| `create_treatment_checkout`    | Write | `POST /treatments/{shop_identifier}` -- Create a treatment-based checkout                         |

<Note>
  The `product:read` and `order:read` permissions are shared between the Management API and the Public API. If a key has `product:read`, it can use both `GET /products/` on the Management API and `GET /products/{shop_identifier}` on the Public API (assuming the key is valid for both).
</Note>

## Choosing the Right Permissions

Follow the **principle of least privilege** -- only grant the permissions your integration actually needs.

### Common Scenarios

| Integration Use Case                                | Recommended Permissions                                                                    |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| Pharmacy order management system                    | `orders_read`, `orders_write`                                                              |
| Pharmacy stock sync                                 | `stock_read`, `pharmacy_sku_write`                                                         |
| Pharmacy order + stock management                   | `orders_read`, `orders_write`, `stock_read`, `pharmacy_sku_write`                          |
| Pharmacy with webhook notifications                 | Add `webhooks_read`, `webhooks_write` to any of the above                                  |
| Telemedicine provider checkout flow                 | `product:read`, `create_prescription_checkout`                                             |
| Telemedicine provider with order tracking           | `product:read`, `create_prescription_checkout`, `order:read`                               |
| Organisation analytics dashboard                    | `order:read`, `prescription:read`, `doctor:read`, `doctor_statistics:read`, `patient:read` |
| Waiting room integration                            | `waiting_room:read`, `waiting_room:write`, `patient:read`                                  |
| Wallet pass management                              | `wallet_pass_template:read`, `wallet_pass:read`, `wallet_pass_push_notification:write`     |
| Organisation webhook notifications (Management API) | `notification_subscription:read`, `notification_subscription:write`                        |

### Tips

* **Separate read and write** -- If your integration only needs to display data, request only read permissions.
* **Use dedicated keys** -- Create separate API keys for different systems or environments rather than sharing a single key with all permissions.
* **Audit regularly** -- Review your API keys periodically and revoke any that are no longer in use.
* **External Pharmacy API vs. Management API** -- Pharmacy-specific integrations should use the External Pharmacy API with pharmacy API keys. Organisation-wide integrations should use the Management API with management API keys.