Send the key
Put the key in theAuthorization header, after the word Bearer and one space:
Bearer exactly like this, with a capital B. Keys always start with sk-. A request without a valid key gets 401 with {"error": "Unauthorized"}.
Two kinds of keys
The API calls a clinic an organization and a partner account a tenant.
What each key can call
Some endpoints also check the role of the person who created the key. See A key acts with the rights of its creator.To follow an outbound call placed with a partner key, use the call-completed callback, or read the status with a clinic key created by the clinic owner.
Create a clinic key
1
Open the clinic
Sign in to AlloMia and make sure the clinic is selected in the selector at the top of the left menu.
2
Open the API Keys tab
In the left menu, under Organization, click Organization Settings. Open the API Keys tab, and stay on the API Keys tab inside it.
3
Add the key
Click Add Key. In API Key Name, enter a name of 3 to 50 characters, for example the name of the system that will use the key. Click Create API Key.
4
Copy the key
In New API Key Created, click Copy to Clipboard and store the key in your secrets manager right away. It is never shown again.
Create a partner key
1
Sign in with the right account
Use the partner account owner’s account or an account with the Tenant Admin role. Keys created by other roles can only read calls.
2
Select your partner account
Open the selector at the top of the left menu and pick your partner account under Tenants.
3
Open the API Keys tab
In the left menu, under Configuration, click Tenant Settings. Open the API Keys tab. The card is titled Tenant API Keys.
4
Add and copy the key
Click Add Key, enter an API Key Name of 3 to 50 characters, and click Create API Key. In New API Key Created, click Copy to Clipboard.
Key facts
- Format:
sk-followed by 48 hexadecimal characters, 51 characters in all. - Shown once: after you close New API Key Created, the list only shows the first 8 characters, such as
sk-3f9a1.... If you lose a key, create a new one and delete the old one. - Up to 5 active keys per clinic and 5 per partner account. At 5, Add Key is disabled, and hovering over it shows Maximum number of API keys reached. The page also shows how many keys are used, for example 5/5 keys used.
- No expiry: a key works until it is deleted, or until its creator’s account is deactivated.
- The name is for you: it helps you tell keys apart. It isn’t sent with requests.
A key acts with the rights of its creator
AlloMia records who created each key and checks that person’s access on every request:- A clinic key can place outbound calls and read their status only if its creator is the clinic owner or a Tenant Admin. A key created by another clinic member can only read calls.
- A partner key can manage clinics and place outbound calls only if its creator is the partner account owner or a Tenant Admin. A key created by a Tenant Support member can only read calls.
- A clinic you create with a partner key is owned by the person who created that key.
- If the creator’s AlloMia account is deactivated, the key stops working and returns
401. If the creator stops being the clinic owner, the key loses owner-only access and returns403on those endpoints.
Delete (revoke) a key
1
Find the key
Open the same API Keys tab where the key was created.
2
Delete it
On the key’s row, click the bin icon (Delete API key). In Confirm Deletion, click Delete API Key.
401. You can’t undo a deletion.
Rotate a key
- Create a new key. You need a free slot, since each clinic and partner account can have 5 active keys.
- Deploy the new key to your system.
- Check that requests succeed with the new key.
- Delete the old key.
Authentication errors
See Errors for every error the API returns.
Keep keys safe
- Treat keys like passwords. Anyone who has a key can act with its creator’s rights.
- Keep keys on your server, in a secrets manager or in environment variables. Never put them in browser code, mobile apps or source control.
- Call the API from your server only, over HTTPS.
- Use one key per system and per environment, so you can delete one without stopping the others.
- Never send keys by email or chat.
- If a key may have been exposed, delete it at once and create a new one.
- Rotate keys on a regular schedule.