API identities
An API identity is an automated sender on your account, a bot your integration sends as: for example Appointment reminders or EHR sync. Owners and IT give it a name and an avatar, choose the teams and phone numbers it can use, and attach API keys to it. Staff see it in threads marked as automated, and every message it sends is recorded against it.
An identity isn’t a person: it isn’t listed in the Directory or under People, isn’t a billable seat, can’t sign in, and sends only from its allowed teams and numbers.
The identity is who sends. A key is only how your server proves it’s that identity. One identity can have several keys, so you can rotate keys, or run the same integration from two servers, without changing who the messages come from.
Which keys need an identity
| Key | Needs an identity |
|---|---|
Has messages.write (sends to patients) | Yes. A sending key must be attached to an identity. |
Only reads: messages.read, patients.read, members.read, report and audit reads | No |
Provisioning: members.write, teams.write, patients.write without messages.write | No |
On an account with API identities turned on, creating a key with messages.write asks which identity it belongs to, and a sending key can’t be left without one.
An identity never sends on behalf of a staff member. Messages from your integration always come from the identity, so staff and auditors can tell what your system sent from what a person sent.
Create an identity
Name it
Under Settings → Account → API keys, in the API identities section, an Owner or IT person clicks Create identity and gives it:
- a name staff and patients will recognize, like “Appointment reminders”. Patients see it in secure chat.
- an avatar, shown next to its messages in BloomText.
It’s always marked as automated, so no one mistakes it for a person.
Choose where it can send
Pick the teams and phone numbers the identity can use. Its keys can then send only from those numbers, and read only those teams’ patient conversations. This is the same phone-number limit a key can carry, set once for every key the identity has.
Attach keys
On the same tab, create a key with messages.write and choose the identity it belongs to, or attach an existing key from the identity’s row. See API keys.
What people see
| Who | Sees |
|---|---|
| Staff, in the thread | The identity’s name and avatar, marked as automated |
| Owners and IT, in Message reports | The identity as the sender; the Automated filter shows only identities’ messages |
| Owners and IT, in the Audit log | The identity as the actor, and the key it used; the Automated filter shows only identities |
| Anyone, in the Directory or People | Nothing: identities aren’t listed there |
| Patients, in secure chat | The identity’s name |
| Patients, on SMS | The office’s phone number |
A patient’s reply lands in the sending number’s team inbox, like any other patient message, so a person on that team picks it up.
In the API
Messages an identity sends carry it as their sender:
{ "id": "3f6c1a9e-0b7d-4c55-9a43-8f2d6e1b7a10", "name": "Appointment reminders", "kind": "api_identity" }Sends follow the usual number rules: from must be one of the identity’s numbers; with exactly one, it’s the default; otherwise a send without from returns 422 with code: from_required. See Which number it comes from.
Rotate keys without changing the sender
- Create a second key for the identity and deploy it.
- Revoke the old key.
Messages sent before and after the rotation come from the same identity. Revoking every key stops the identity from sending; it stays on the account, with its history, until an Owner or IT person deletes it.
Today’s default
Until API identities are turned on for your account, a message sent with an API key shows the key’s name, like “Reminder service”, with an API marker, and its sender.kind is api_key. Patients see the clinic. Turning identities on doesn’t change messages already sent.
How this compares
If your IT team knows chat platforms: an API identity works like a Slack bot user or a Discord bot. It’s a named, automated sender with its own avatar and permissions, its tokens belong to it, it can’t sign in as a person, and it doesn’t take a seat.