Skip to main content

Authentication

All RxScale APIs use API key authentication. Include your API key in the X-API-Key header with every request.

API Key Header

Alternative Public API Headers

The Public API also accepts X-RxScale-Authorization as an alternative to X-API-Key. This is supported for backward compatibility with existing integrations.
You can also send the same API key as a bearer token in the 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_uid query 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.
Both credential types are checked against the same permission strings (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_secret for your Auth0 application
  • The Auth0 domain to request tokens from
  • The scopes to request, matching the permissions your integration needs
Scopes alone are not enough. Every Bearer token is resolved to an account in your organisation before its scopes are consulted. For a machine-to-machine application, Auth0 sets the token’s sub claim to <client_id>@clients — an identity no interactive sign-in ever creates. RxScale must register that exact sub as a service principal in your organisation as part of provisioning the application. Until that is done, every request answers 401 with:
This is part of the onboarding your account manager performs; it is not something you can configure in Auth0 yourself. If you see this response after receiving working credentials, the client’s sub has not been registered — quote your client_id and ask for it to be linked to your organisation.
Request an access token using the OAuth 2.0 client credentials grant:
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.
Use the returned access_token as a bearer token:
The audience for the Management REST API is the API root, https://api.rxscale.com/v1/management — not a specific endpoint path. A token issued for a different audience is rejected with 401.

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:write even 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 at https://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)

  1. Log in to the Admin Tool
  2. Navigate to Settings → API Keys
  3. Click Create API Key
  4. Enter a display name for the key
  5. Select the permissions you want to grant (e.g. order:read, telemed_product:read, prescription:read)
  6. Click Create — the key will be shown once. Copy and store it securely.
The API key is only shown once at creation time. If you lose it, you will need to create a new one.

As a Pharmacist (External Pharmacy API)

  1. Log in to the Pharmacy Tool
  2. Navigate to Settings → API Keys
  3. Create a new key scoped to your pharmacy or pharmacy group
  4. 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:
For security, RxScale returns 404 Not Found instead of 403 Forbidden when you try to access a resource outside your scope. This prevents resource enumeration.
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.