Keys for connecting other software

• A key works only with the clinic account it was created in.
• Today, software with a key can list your clinic’s calls and read a call’s details, including its summary and links to its transcript and recording. It can also start a call with one of your AI agents and check how it went. See Starting calls from your own software.
• A key acts for the person who created it. If that person’s AlloMia account is deactivated, the key stops working.
• Only keys created by the person who created the clinic account can start calls. A key created by anyone else can read calls, but AlloMia refuses it when it starts a call. See Owner or User: who can do what.
• A key gives access to patients’ call details. Treat it like a password.

• Agree with the clinic on who creates and deletes keys. Usually it’s the person who created the clinic account, since only their keys can start calls.
• Check that you’re in the right clinic: its name shows at the top of the menu on the left. See Switching between clinics.
• A clinic can have up to 5 keys at a time. Keys don’t expire: a key works until you delete it.

1. In the menu on the left, under Organization, click Organization Settings.
2. Click the API Keys tab. Stay on the API Keys tab inside it.
3. Click Add Key.
4. In API Key Name, name the key after the software that will use it, for example “Scheduling system”. Use 3 to 50 characters.
5. Click Create API Key.
6. The New API Key Created window shows the key. Click Copy to Clipboard, then paste the key right away into the other software’s settings or into your password manager.

This is the only time the full key is shown. Afterwards, the list shows only its first characters. If you lose a key, create a new one and delete the old one.

• Keys start with sk-.
• The other software sends the key in the Authorization header of each request to https://allomia.com: Authorization: Bearer sk-…
• A request with a missing, wrong or deleted key gets HTTP 401 with the error Unauthorized.

1. Go to Organization Settings, then the API Keys tab.
2. On the key’s row, click the bin icon (Delete API key).
3. In the Confirm Deletion window, click Delete API Key.

The key stops working right away for every system that uses it, and this can’t be undone. To replace a key without a break, create the new key, put it in the other software, then delete the old one.

• Use one key per system. Then you can delete one key without stopping the others.
• Keep keys in a password manager or in the other software’s secret settings. Never send them by email or chat, and never put them in code that others can see.
• When a system is retired, or when someone who created keys leaves the clinic, delete those keys. Removing a colleague from the clinic account doesn’t delete the keys they created.
• If someone else may have seen a key, delete it and create a new one.

The second tab inside API Keys, External API Keys, doesn’t create AlloMia keys. It stores keys for your clinic’s other software, encrypted, so that a software partner that manages your AlloMia account can use them when it sets up connections for your clinic. Most clinics never need it.

If your partner asks you to add a key there, click Add Key, enter the Key Name exactly as your partner gives it and the API Key Value, then click Add Key. The value isn’t shown again. To replace it, click the pencil icon on its row (Edit API key), enter the new value and click Save Changes. Don’t put AlloMia keys there.

• Add Key is grey: the clinic already has 5 keys (“Maximum number of API keys reached”). Delete one you no longer use.
• HTTP 401 Unauthorized: the key is wrong or was deleted, or the account of the person who created it was deactivated. Create a new key.
• HTTP 403 “Insufficient permissions” when starting a call: the key wasn’t created by the person who created the clinic account. Ask that person to create one.
• You closed the window before copying the key: it can’t be shown again. Delete it and create a new one.