# API keys

> Create an organization API key for the Patient API, send it as a Bearer token, and know what it can reach, how to rotate it, and how to keep it safe.

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

An API key lets your server handle patient communication with no one signed in: syncing patients from your EHR, sending reminders, running campaigns, and reading what patients write back.

### Your organization gets API access

API access is turned on for organizations with a signed BAA. [Request API access](https://calendly.com/tyler-bloom/bloomtext-homepage-demo-request?utm_campaign=api-access) to get started.

### An org admin creates a key

In BloomText, an org admin creates a key under **Settings → API keys**, choosing:

- a **name**, like "Reminder service". Messages the key sends come from this name, so staff know where they came from; patients see the clinic.
- its **[scopes](https://www.bloomtext.com/developers/api/authentication/#scopes)**. A key that only sends reminders needs `messages.write` and `patients.read`.
- a **default phone number**, used when a send doesn't pass `from`. See [Phone numbers](https://www.bloomtext.com/developers/api/send-messages/#which-number-it-comes-from).

BloomText shows the key once. Store it in your secrets manager right away.

### Your server sends it

Send the key as a Bearer token:

```bash filename="Request"
curl https://api.bloomtext.com/v1/organization \
  -H "Authorization: Bearer $BLOOMTEXT_API_KEY"
```

```json filename="Response · 200 OK"
{ "id": "6db1e3f5-9b7f-4f2b-8be1-0f1e1d7d7d8c", "name": "Example Clinic" }
```

## What a key can reach

- Patients: [find](https://www.bloomtext.com/developers/api/reference/list-patients/) them by phone number or MRN, and [retrieve](https://www.bloomtext.com/developers/api/reference/get-patient/), [create](https://www.bloomtext.com/developers/api/reference/create-patient/), [update](https://www.bloomtext.com/developers/api/reference/update-patient/), [delete](https://www.bloomtext.com/developers/api/reference/delete-patient/), and [import](https://www.bloomtext.com/developers/api/reference/create-patient-import/) them.
- Patient communication: [message a patient](https://www.bloomtext.com/developers/api/send-messages/), and [read patient messages](https://www.bloomtext.com/developers/api/read-messages/) in a time range, for one patient, or across all patient conversations.
- Campaigns: [create, change, run, and delete](https://www.bloomtext.com/developers/api/campaigns/) them.

A key reads with [`GET /patient-messages`](https://www.bloomtext.com/developers/api/reference/list-patient-messages/) and [`GET /patient-conversations`](https://www.bloomtext.com/developers/api/reference/list-patient-conversations/), which cover patient conversations only. It never sees staff conversations; see [What the API can reach](https://www.bloomtext.com/developers/api/concepts/#what-the-api-can-reach). The `/me` endpoints, for an admin's own conversations, need OAuth. Staff-side calls, like the staff directory, reactions, participants, or sending in a staff conversation, return `403` with `code: oauth_required`.

> **Warning:** Keep keys on your server. Never put a key in a browser, a mobile app, a public repository, or an AI prompt.

## Rotate or delete a key

To rotate a key, create a second one, deploy it, then delete the old one. Both work during the overlap.

Delete a key in BloomText at any time. It stops working on the next request.