Errors & security¶

HTTP status codes¶

Code	Meaning
`400`	Validation error (missing field, invalid `shop_id`, etc.)
`401`	Missing/invalid API key or missing/invalid Bearer token
`403`	Org mismatch or missing integration scope
`404`	Resource not found
`500`	Server error

{ "error": "human-readable message" }

Extended errors:

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

{
  "error": "insufficient_scope",
  "message": "Missing scope: orders.read"
}

Some unauthorized responses use this format:

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

{ "message": "No API key found in request", "request_id": "…" }

Step	Protection
API key	Required for token exchange and v1 order-requests
JWT	Bearer token required on all v2 routes
Org path match	URL `{orgId}` must match token `org_id`
Scopes	Integration JWT limited per route

Never use org A's API key to request a token for org B's URL. Requests are rejected when the key does not belong to the organization in the path.

Integration JWTs expire after 1 hour. Rotate by re-calling /auth/token. Do not cache tokens longer than expires_in.

Secret	Storage
PharmaOne API key	Secret manager / env — never commit to git
Webhook signing secret	Shown once at subscription create
JWT	Memory only — treat as bearer credential

These settings are managed in PharmaOne Manager (not via PharmaOne API keys):

Purpose	Where in Manager
Create / revoke API keys	Org Settings → Integrations → External API keys
Webhook subscriptions	Org Settings → Integrations → Webhook subscriptions
Test webhook delivery	Webhook subscription → Send test event