Authentication

PharmaOne external integrations use per-organization API keys and short-lived JWTs.

Step 1 — Obtain an API key

1. Log in to Manager as organization owner.
2. Open Org Settings → Integrations → External API keys.
3. Click Create key — the secret is shown once. Store it securely.

Maximum 5 active keys per organization.

Step 2 — Exchange API key for JWT

POST /api/v2/public/orgs/{orgId}/auth/token
apikey: {your_api_key}
Content-Type: application/json

Accepted key locations:

Location	Example
Header apikey	apikey: abc123…
Header X-API-Key	X-API-Key: abc123…
Query apikey	?apikey=abc123…

Success — 200 OK

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Tokens expire after 1 hour. Call the token endpoint again to refresh.

JWT claims

Claim	Value
org_id	Organization id (must match URL {orgId})
scopes	Granted permissions (see Scopes)
iss	pharmaone-integration
sub	integration

Failure — 401 Unauthorized

Invalid or missing API key. Kong may return:

{
  "message": "Unauthorized",
  "request_id": "cd736522b658367429e55f72dc5c6040"
}

The backend may return:

{ "error": "Invalid or missing API key" }

Live request/response samples: Examples.

Use the correct org key

You cannot mint tokens for another organization without that organization's API key. The {orgId} in the URL must match the key's organization.

Step 3 — Call v2 endpoints

GET /api/v2/public/orgs/{orgId}/orders?limit=10
Authorization: Bearer {access_token}
Content-Type: application/json

Org path matching

The {orgId} in the URL must match the JWT org_id. Mismatch returns:

{
  "error": "org_mismatch",
  "message": "Token org_id does not match URL orgId"
}

v1 order-requests (no JWT)

POST /api/v1/public/orgs/{orgId}/order-requests
apikey: {your_api_key}
Content-Type: application/json

Same JSON body as v2 order-requests. Send your API key on every request.

For telemedicine partners who only receive a shop URL (not Manager), see External Telemedicine Connector — POST {shop}/api/v1/external-order.