# API identities

> Give your integration its own automated sender, a bot on your account with a name, avatar and chosen teams and numbers, and attach API keys to it so every message it sends comes from that sender.

Source: https://www.bloomtext.com/developers/api/api-identity/

> Your BloomText team turns this on for your account. [Request access](https://calendly.com/tyler-bloom/bloomtext-homepage-demo-request?utm_campaign=api-access&utm_content=api-identity)

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.

```mermaid
flowchart LR
  subgraph Account
    ID["API identity: Appointment reminders (automated)"]
    K1[Key: reminders-prod] --> ID
    K2[Key: reminders-rotation] --> ID
    ID -->|sends from| N["Pediatrics number (Front desk team)"]
  end
  N --> P[Patient]
  P -->|replies| T[Front desk team inbox]
```

## 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](https://www.bloomtext.com/developers/api/api-keys/#limit-a-key-to-phone-numbers) 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](https://www.bloomtext.com/developers/api/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](https://www.bloomtext.com/developers/api/reporting-and-audit/#in-bloomtext-for-owners-and-it) | The identity as the sender; the **Automated** filter shows only identities' messages |
| Owners and IT, in the [Audit log](https://www.bloomtext.com/developers/api/reporting-and-audit/#in-bloomtext-for-owners-and-it) | 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`:

```json filename="Message.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](https://www.bloomtext.com/developers/api/send-messages/#which-number-it-comes-from).

## Rotate keys without changing the sender

1. Create a second key for the identity and deploy it.
2. 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.