Skip to main content
Every API request must carry an API key. Keys are created in the AlloMia dashboard by you or by the clinic. AlloMia staff don’t issue them.

Send the key

Put the key in the Authorization header, after the word Bearer and one space:
Write 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.
The second tab inside API Keys, External API Keys, stores keys for the clinic’s other software. It doesn’t create AlloMia API keys. If you need outbound calls, ask the clinic owner to create the key. If a clinic user creates the key for you, you can send them the help-center article Keys for connecting other software.

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 returns 403 on those endpoints.
So create keys from an account that has the role you need and that will stay in place. Before the creator leaves or changes role, create a replacement key from another qualified account, switch your system to it, then delete the old key.

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.
Access stops immediately. Requests that use the deleted key get 401. You can’t undo a deletion.

Rotate a key

  1. Create a new key. You need a free slot, since each clinic and partner account can have 5 active keys.
  2. Deploy the new key to your system.
  3. Check that requests succeed with the new key.
  4. 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.