API keys
An API key lets your server work with BloomText with no one signed in: syncing patients from your EHR, sending reminders, reading what patients write back, and managing staff across your organizations.
Your organization gets API access
BloomText turns on API access once your BAA is signed. Request API access to get started. Until then, the API keys tab says so and offers the same request.
An Owner or IT person creates a key
Keys belong to your BloomText account, the subscription your organizations share. Once API access is on, an account Owner or IT person creates keys under Settings → Account → API keys → Create API key. Each key has:
- a name, like “Reminder service”, so you can tell your keys apart.
- for a key with
messages.write, the API identity it sends as: an automated sender, set up in the API identities section of the same tab, with its own name, avatar, teams and numbers. It isn’t a person, a seat, or listed under People. Several keys can share one identity, so rotating a key keeps the sender. Read-only and provisioning keys need no identity. Until identities are on for your account, staff see a sending key’s messages under the key’s name with an API marker, and patients see the clinic. - the organizations it reaches: all of them, including ones added later, or only the ones picked. Separate clinics that run as separate organizations, like Northside Clinic and Eastside Clinic, can each get their own key. See Organizations a key reaches.
- its scopes. A key that only sends reminders needs
messages.writeandpatients.read. - an expiry: 1 day, 7 days, 30 days, 90 days (the default), 1 year, or never. Never asks you to confirm. See Expiry.
If your account doesn’t have the Account page yet, BloomText creates your keys. Organizations have no API keys tab of their own.
A key made in Settings has no default phone number, so a send without from works only when your organization has one number. See Phone numbers.
The key is shown once. Store it in your secrets manager right away. Owners and IT see every key under Settings → Account → API keys.
Your server sends it
Send the key as a Bearer token:
curl https://api.bloomtext.com/v1/organization \
-H "Authorization: Bearer $BLOOMTEXT_API_KEY"{ "id": "6db1e3f5-9b7f-4f2b-8be1-0f1e1d7d7d8c", "name": "Northside Clinic" }Organizations a key reaches
A key that reaches one organization acts on it with no extra parameter. A key that reaches several needs org_id on every call, taken from GET /orgs:
curl "https://api.bloomtext.com/v1/patients?phone=%2B15555550123&org_id=$ORG_ID" \
-H "Authorization: Bearer $BLOOMTEXT_API_KEY"- Leaving out
org_idon a key that reaches several organizations returns400withcode: org_id_required. - An
org_idthe key can’t reach returns403withcode: org_not_reachable. - Keys made before accounts were turned on keep working with no
org_id: each reaches only its own organization.
Limit a key to phone numbers
A key can also be limited to some of the account’s phone numbers. Use it when one system serves one department, like a reminder service that should only ever text from the pediatrics number.
When an Owner or IT person creates the key, they choose Only some phone numbers under the organizations it reaches and pick the numbers, grouped by organization. A limited key then:
| Call | With a phone-number limit |
|---|---|
| Send a message | from must be one of the key’s numbers. With exactly one number, that number is the default and from can be left out. Otherwise a send without from returns 422 with code: from_required, listing the key’s numbers. |
| Read patient messages and conversations | Only conversations owned by the teams of the key’s numbers. |
| List phone numbers | Only the key’s numbers. |
| Patients | Unchanged: patients are organization-wide, since a patient record has no number. |
| Members and teams | Unchanged: the limit applies to message scopes only. |
A number belongs to one organization, so limiting a key to numbers also limits it to those numbers’ organizations.
Reads follow each number’s team, not the number itself. If a team has two numbers and the key has one of them, the key reads that team’s conversations on both.
What a key can reach
In each organization it reaches, a key works across the whole organization, every team’s patients and patient conversations, within its scopes, unless it has a phone-number limit. Keep that in mind when deciding who gets a key.
- Patients: find them by phone number or MRN, and retrieve, create, update and delete them.
- Patient communication: message a patient, and read patient messages in a time range, for one patient, or across all patient conversations.
- Staff: list organizations, add, change and remove members, and place them on teams. See Manage members.
- Turned on per account: campaigns and patient imports.
A key reads with GET /patient-messages and GET /patient-conversations, which cover patient conversations only. It never sees staff conversations; see What the API can reach. A person’s own conversations under /me, the staff directory, reactions and participants use OAuth; an API key calling them gets 403 with code: oauth_required.
Members a key adds show Managed by API in BloomText, and only an API key can change them. If the account’s Okta rules later match those people, Okta takes them over at the next rule save; the API then gets 409 with code: managed_by_identity_provider. See Manage members.
Keep keys on your server. Never put a key in a browser, a mobile app, a public repository, or an AI prompt.
Expiry
A key stops working when its expiry passes. Requests then return 401 with code: key_expired.
Under Settings → Account → API keys, an Owner or IT person can give a key a new expiry from the same choices, counted from that moment. This works even after the key has expired. A key that expires within 14 days is highlighted there.
A key that never expires stays valid until someone revokes it. If it leaks, anyone can use it until then, so pick an expiry unless you rotate keys some other way.
Rotate or revoke a key
To rotate a key, create a second one, deploy it, then revoke the old one. Both work during the overlap.
An Owner or IT person can revoke a key at any time under Settings → Account → API keys. It stops working on the next request, which returns 401 with code: key_revoked. A revoked key can’t be restored. Messages it sent keep its name.