Authentication

Every request is authenticated with an API key sent as a Bearer token:

Header


Authorization: Bearer bt_live_4f7c2a9e1b...

Requests without a valid key return 401 Unauthorized. All requests must use HTTPS.

Getting a key

API keys are issued to organizations with a signed BAA. Request API access to get started.

Your organization is enabled

After the BAA is signed, we turn on API access for your organization.

An admin creates an app user

The app user represents your integration in conversations. Give it a clear name, like “Intake Bot”.

The admin issues a key with scopes

Pick only the scopes your integration needs. The key is shown once, so store it in your secrets manager straight away.

Keep keys server-side. Never put a key in a browser, a mobile app, a public repository, or an AI prompt that leaves your infrastructure.

Scopes

Each key carries the scopes an admin grants it. A request outside the key’s scopes returns 403 with code: insufficient_scope. Every endpoint in the API reference lists the scope it needs.

Scope	Allows	Endpoints
`organization:read`	Read the organization	Retrieve the organization
`users:read`	List and read members	List users, Retrieve a user
`conversations:read`	List and read conversations	List, Retrieve
`messages:read`	Read messages and replies	List messages, List replies
`messages:write`	Send messages and replies	Send a message
`reactions:read`	Read reactions	List reactions
`reactions:write`	Add and remove reactions	Add, Remove
`participants:read`	List participants	List participants
`participants:write`	Add and remove participants	Add, Remove
`broadcasts:read`	Read broadcasts	List, Retrieve, Messages
`exports:read`	Check and download exports	Retrieve an export
`exports:write`	Start exports	Export a conversation

Common scope sets

Reminder service

Posts reminders and nothing else.


conversations:read  messages:write

Two-way assistant

Reads incoming messages, replies, and reacts to acknowledge.


conversations:read  messages:read  messages:write  reactions:write

Records archiver

Exports conversation history on a schedule.


conversations:read  exports:write  exports:read

Keys for AI agents

An AI agent acts on its own judgment, so give it less access than a script you wrote line by line.

Give the agent its own app user

Never share a key between an agent and another integration. A dedicated app user, named so staff recognize it (like “Scheduling Assistant”), lets you audit and revoke the agent on its own.

Start read-only

Begin with conversations:read and messages:read. Have the agent post drafts to a staff group for review, and add messages:write for patient conversations only once you trust its output.

Limit where it can go

Add the app user only to the conversations the agent needs. Membership is the boundary: an agent can’t read or post anywhere it hasn’t been added.

Keep the key out of the model

Store the key in your agent’s secret store or environment, like BLOOMTEXT_API_KEY. Never put it in a prompt, a tool description, or chat history.

The model provider behind your agent sees whatever the agent reads. If the agent can read patient conversations, the provider needs a BAA with your organization.

See Build an AI agent and the MCP server for the full setup.

Conversation access

Scopes decide what a key can do. Conversation membership decides where. A key can read or write a conversation only while its app user is a participant, and a request for any other conversation returns 403 with code: conversation_membership_required.

Adding a participant with participants:write is limited to existing organization members. It never widens what your app user can see.

Rotating and revoking keys

Rotate by issuing a second key for the same app user, deploying it, then revoking the old one. Both work during the overlap.
Revoke from BloomText at any time. Revocation takes effect on the next request.
Remove the app user from a conversation to cut off just that conversation.

Verify your key

A quick way to check a key works and see which organization it belongs to:

cURL


curl https://api.bloomtext.com/v1/organization \
  -H "Authorization: Bearer $BLOOMTEXT_API_KEY"

JavaScript


const response = await fetch('https://api.bloomtext.com/v1/organization', {
  headers: { Authorization: `Bearer ${process.env.BLOOMTEXT_API_KEY}` },
})
console.log(response.status, await response.json())

Python


import os
 
import requests
 
response = requests.get(
    "https://api.bloomtext.com/v1/organization",
    headers={"Authorization": f"Bearer {os.environ['BLOOMTEXT_API_KEY']}"},
)
print(response.status_code, response.json())

Go


req, _ := http.NewRequest("GET", "https://api.bloomtext.com/v1/organization", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("BLOOMTEXT_API_KEY"))
res, err := http.DefaultClient.Do(req)

Ruby


uri = URI("https://api.bloomtext.com/v1/organization")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("BLOOMTEXT_API_KEY")}"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

Response · 200 OK


{
  "id": "6db1e3f5-9b7f-4f2b-8be1-0f1e1d7d7d8c",
  "name": "Riverside Family Clinic"
}