Authentication
All RxScale APIs use API key authentication. Include your API key in theX-API-Key header with every request.
API Key Header
Alternative Public API Headers
The Public API also acceptsX-RxScale-Authorization as an alternative to X-API-Key. This is supported for backward compatibility with existing integrations.
Authorization header.
New integrations should use
X-API-Key unless your platform requires bearer-token
authentication. The X-RxScale-Authorization and Authorization: Bearer headers
are only supported on Public API endpoints.API Key Types
Pharmacy API Keys
Pharmacy API keys can be scoped to:- A single pharmacy — The key can only access data for that specific pharmacy. If that pharmacy is removed, the key stops working and every request returns
401. - A pharmacy group — The key can access data for any pharmacy in the group. When using a group-wide key, you must include the
pharmacy_uidquery parameter to specify which pharmacy you are acting on.
Management API Keys
Management API keys are scoped to an organisation. They can access data for all entities within that organisation.Management API: API Key or OAuth Bearer Token
Every Management API endpoint — including the MCP endpoint — accepts either of these credentials:X-API-Key— the organisation-scoped API key described above.Authorization: Bearer <token>— an OAuth 2.0 access token issued by RxScale’s Auth0 tenant.
order:read, product:write, questionnaire:read, …). An API key’s permissions are set when the key is created; a Bearer token’s permissions come from its OAuth scope (or Auth0 RBAC permissions) claim.
Send
X-API-Key or Authorization: Bearer, not both. If X-API-Key is present it takes priority and the request is authenticated as an API key.Getting a Bearer token
RxScale provisions the Auth0 application for your integration as part of onboarding — you do not register your own Auth0 tenant or client, and you never paste an API key into an OAuth client configuration. Contact your RxScale account manager to receive:- A
client_id/client_secretfor your Auth0 application - The Auth0 domain to request tokens from
- The scopes to request, matching the permissions your integration needs
scope is a space-separated list of the permission strings your integration needs (the
same strings used by API keys, e.g. order:read, product:write). Only request the
scopes you actually use — Auth0 rejects a scope your client isn’t registered for, and a
broader grant than your integration needs is unnecessary exposure if the token leaks.access_token as a bearer token:
The two credential types carry their permissions independently
The two credentials check the same permission strings, but they do not share a permission store, and neither one limits the other:
Three consequences worth planning around:
- A Bearer token’s scopes are not narrowed by your API keys. A token may carry
product:writeeven if no API key in your organisation has that permission. Scopes are granted per Auth0 application; they are not filtered against your keys’ permissions afterwards. - Removing a permission from an API key does not affect Bearer tokens, and reducing an Auth0 application’s scopes does not affect API keys. They are two separate revocations — ask for both when an integration’s access should be reduced.
- A change to an Auth0 application’s scopes does not shorten a token that is already out. Access tokens are self-contained and are accepted until they expire.
Cutting a compromised integration off immediately. Because every Bearer token is
resolved to a service principal in your organisation on every request, un-registering
that service principal stops all of that application’s tokens at once — issued ones
included, without waiting for expiry. That, plus rotating the
client_secret, is the
fastest containment path; ask your RxScale account manager for both.Which 401 you are looking at
Both failures below answer 401, but they have different fixes:
The MCP endpoint uses a separate audience
The Management API also exposes an MCP (Model Context Protocol) endpoint for AI clients such as Cursor or Claude Desktop, reachable athttps://api.rxscale.com/v1/management/mcp. It serves the same organisation data through a curated set of tools, but its Bearer tokens are issued for a different, separately-registered Auth0 audience — the MCP endpoint’s own URL, not the REST API root above. A token scoped to one audience is rejected on the other. See the Management API MCP guide for connection details.
Permissions
Each API key has a set of permissions that control which endpoints it can access. Common permissions include:Creating API Keys
As an Admin (Management API & Public API)
- Log in to the Admin Tool
- Navigate to Settings → API Keys
- Click Create API Key
- Enter a display name for the key
- Select the permissions you want to grant (e.g.
order:read,telemed_product:read,prescription:read) - Click Create — the key will be shown once. Copy and store it securely.
As a Pharmacist (External Pharmacy API)
- Log in to the Pharmacy Tool
- Navigate to Settings → API Keys
- Create a new key scoped to your pharmacy or pharmacy group
- Select the required permissions (e.g.
orders_read,orders_write,stock_read)
Pharmacy API keys can be restricted to a single pharmacy or cover an entire pharmacy group. Group-wide keys require the
pharmacy_uid parameter on each request.Error Responses
If authentication fails, you will receive one of these responses:Requests rejected for a wrong secret on one of your API keys (
401) or a missing permission
(403) are recorded in your organisation’s audit log.