Authenticate with an integration key
Every request sends a key that belongs to one integration client at one practice. Here's where the key comes from and what it's allowed to do.
On this page
Every request to the API sends an integration key as a bearer token:
curl https://dashboard.practor.app/api/v1/practitioners \
-H "Authorization: Bearer $PRACTOR_API_KEY"The key says which practice you're working in. There's no practice id in the URL and no way to reach another practice's records with it.
Where a key comes from
A practice owner creates it in Practor, under Organization settings, then Integrations. The practice needs the Integrations add-on switched on first.
- Create a client for your software. A client is one integration, with its own permissions, keys, webhooks and activity log.
- Give it permissions under Permissions. The billing preset grants what a practice system usually needs: create, read and update patients and medical insurance, create and read encounters, create, read and update invoices (update is what lets you issue one), submit and read claims, and read payments. A practice owner confirms changes to keys and permissions with their second factor.
- Create a key under Keys. It's shown once, in full. Store it as a secret on your server; Practor keeps only a one-way digest and the first characters, which is what the practice sees in the key list and the activity log.
A key lasts 90 days unless the owner picks another expiry, up to 365 days. The practice gets a warning 14 days and 3 days before it expires. A client can hold two live keys, so you can deploy a new one before the old one is revoked.
Never put a key in a browser, a mobile app or anything else a user can open. It acts for the whole practice.
What a key can do
Only what its client's permissions allow. Each endpoint in the API reference says which permission it needs, such as PATIENTS:CREATE. A request without it gets a 403 that names the permission, and the practice owner can add it under Permissions. A change takes effect on the very next request.
When a key is refused
| Status | Why |
|---|---|
401 | No key was sent, or the key can't be used: unknown, revoked or expired, its client suspended, or the call came from outside the client's allowed addresses. Every one of these gets the same answer, so an old key can't be used to learn which it is. The practice's audit log shows the reason against the request id. |
403 | The client lacks the permission the endpoint needs, or the practice's Integrations add-on is off. The body names the permission. |
A client can be limited to fixed IP ranges under its details. When a key is used from an address it hasn't been used from before, the practice is told. After 30 refused requests from one address in 10 minutes, that address is refused for 10 minutes more, whatever key it sends.
Every request that sends a key, allowed or refused, is written to the practice's audit log with the key's prefix, the address and the patient it touched. Requests with no key are recorded once a minute per address, so nobody can flood the log.