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.
# A key with only `orders_read` can list orders...
curl -X GET "https://api.rxscale.com/v1/external-pharmacy-api-v1/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-v1/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
Permissions are set during API key creation. Contact your RxScale account manager to add or change permissions on an existing key.
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 |
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 |
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.
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) |
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 |
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.
Notification Subscriptions
The notification subscription endpoints (/notification-subscriptions/) on the Management API do not require a specific granular permission — any valid Management API key can access them.
| Endpoint | Method | Description |
|---|
/notification-subscriptions/ | GET | List webhook subscriptions |
/notification-subscriptions/ | POST | Create a webhook subscription |
/notification-subscriptions/ | DELETE | Remove a webhook subscription |
/notification-subscriptions/test | POST | Send a test webhook |
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 |
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 |
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).
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 |
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.