Authentication and scopes
Clinic-owned API keys for server-to-server access.
Send a Bearer token
Send exactly one Authorization: Bearer <token> header over HTTPS. Query parameters, cookies and portal login sessions do not authenticate a public API request. Tokens belong on your server and must never appear in browser code, URLs, analytics, screenshots or logs.
Production tokens begin with bp_live_; nonproduction tokens begin with bp_test_. A token also contains a public key identifier and a random secret. The prefix identifies its environment; a token from another environment will not work.
Choose the least access you need
| Scope | Operations |
|---|---|
clinic:read | Read the clinic attached to this key |
patients:read | List patients and read a patient |
results:read | List approved results, read a result and list its final observations |
Every key grants clinic-wide access within its scopes, across the clinic’s doctors. Scopes cannot restrict a key to an individual patient or doctor. Use a separate key for each integration and environment.
Create and store a key
A doctor acting in the clinic’s Doctor context can manage keys in Connectors → Clinic API access. Choose a descriptive name, the scopes and an expiry between 1 and 365 days. The initial expiry selection is 90 days. A clinic can have at most 20 active, unexpired keys.
The complete token is shown once, after creation. Copy it into your secret manager before dismissing the reveal. Later lists contain metadata only; an existing secret cannot be recovered. If it is lost, create a replacement and revoke the old key.
Rotate without interrupting your integration
- Create a replacement key with the scopes you need.
- Store the replacement in your server’s secret manager and update the integration.
- Verify an authorized read with the replacement.
- Revoke the old key in the portal.
Revocation and expiry stop new authorized reads. An already admitted read can finish; revocation cannot retract data already sent.
Keys outlive their issuer
A key belongs to its clinic. Issuer logout or removal from the clinic does not automatically revoke it. When offboarding staff or an integration, revoke every key they knew. Review active keys regularly and revoke unused access.
An invalid, malformed, expired, revoked or wrong-environment key receives the same 401 response. A valid key lacking the requested scope receives 403. See errors and retries.