Authentication

Every request to the BlueReacher API is authenticated with an API key sent in an Authorization header. There are no OAuth flows, no request signing, and no session cookies. One header, one key.

API key format

A BlueReacher key is a single string that starts with bluereacher_:

bluereacher_your_api_key

Treat the key as opaque. The characters after the prefix are random and carry no meaning you should parse. Store the whole string, prefix included, and pass it through unchanged. Two rules for storage:

Store it as a variable-length string. Key length can change over time, so do not cap the column or config field at a fixed size.
Match on the bluereacher_ prefix if you need to detect keys in logs or scrub them from output.

Where keys come from

Keys are generated per customer in the BlueReacher dashboard under Settings, API Keys. Create one, give it a name that says where it runs (production-crm, staging-worker), and copy it immediately. The full key is shown once at creation. After that the dashboard displays only the prefix and last four characters so you can identify a key without seeing it. You can hold several active keys at once. Use one key per service or environment. When something goes wrong you can then revoke a single key instead of taking every integration offline. A key is scoped to your account. It can send only from lines assigned to you, and it can read only your own messages and contacts.

Sending the key

Send the key as a bearer token on every request.

Header	Value	Required
`Authorization`	`Bearer bluereacher_your_api_key`	Yes, on every request
`Content-Type`	`application/json`	On requests with a JSON body

The base URL is https://api.bluereacher.com/functions/v1/.

Verify a key

The fastest way to confirm a key works is to list your lines:

curl https://api.bluereacher.com/functions/v1/lines \
  -H "Authorization: Bearer bluereacher_your_api_key"

A working key returns your lines:

{
  "data": [
    {
      "line_id": "line_8fq2n4kd",
      "from": "+14155550142",
      "channel": "imessage",
      "status": "active",
      "created_at": "2026-07-24T15:04:05Z"
    }
  ]
}

Authenticated request in JavaScript

const response = await fetch("https://api.bluereacher.com/functions/v1/messages", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BLUEREACHER_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    from: "+14155550142",
    to: "+14155550188",
    content: "Thanks for the call today. Sending the pricing over now.",
    channel: "imessage",
    external_id: "crm_9f21"
  })
});

if (response.status === 401 || response.status === 403) {
  throw new Error(`Auth failed: ${JSON.stringify(await response.json())}`);
}

const message = await response.json();
console.log(message.status);

Authenticated request in Python

import os
import requests

response = requests.post(
    "https://api.bluereacher.com/functions/v1/messages",
    headers={
        "Authorization": f"Bearer {os.environ['BLUEREACHER_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "from": "+14155550142",
        "to": "+14155550188",
        "content": "Thanks for the call today.",
        "channel": "imessage",
    },
    timeout=30,
)

if response.status_code in (401, 403):
    raise RuntimeError(response.json())

print(response.json()["status"])

Both examples read the key from an environment variable. Do that in your own code too.

Keeping keys safe

An API key can send messages from your lines and read your message history. Anyone holding it can do the same. Handle it like a database password.

Server side only. Call the API from your backend, a serverless function, or a workflow tool. Never put a key in browser JavaScript, a mobile app bundle, a Chrome extension, or an HTML page. Anything shipped to a device can be read off that device.
Never commit keys to source control. Use environment variables or a secret manager (AWS Secrets Manager, Doppler, 1Password, your platform’s built-in store). Add .env to .gitignore before the first commit, not after.
Keep keys out of logs and tickets. Scrub any string starting with bluereacher_ from request logs and error reports. Do not paste a key into a support ticket, a screenshot, or a shared channel. If you need help debugging, send the key prefix and last four characters.
Separate keys per environment. Production, staging, and each third-party tool get their own key. Revoking one then costs you one deploy, not five.
Rotate on any suspicion of exposure. A key in a public repo, a shared screen, a departed contractor’s laptop, or a vendor breach all count. You do not need proof of misuse to rotate. Assume exposure means compromise.

Rotating a key

Rotation takes four steps and no downtime:

Create a new key in the dashboard with the same name plus a version suffix.
Deploy the new key to your service and restart it.
Watch traffic on the new key in the dashboard until you see requests landing.
Revoke the old key.

Revocation takes effect on the next request. Any request that arrives with a revoked key gets a 401.

401 versus 403

Both mean the request was rejected. They fail for different reasons and need different fixes.

Status	Meaning	Typical cause	Fix
`401 Unauthorized`	We could not identify you	Missing `Authorization` header, malformed header, typo in the key, revoked or deleted key	Check the header format, then check the key value against the dashboard
`403 Forbidden`	We identified you, and this action is not allowed	Requesting a `line_id` or `contact_id` that belongs to another account, using a channel not enabled on your plan, account suspended for billing or policy	Check the resource ID belongs to you, then check your plan and account status

Short version: 401 is about the key, 403 is about permissions. Error responses share one shape:

{
  "error": {
    "status": 401,
    "code": "invalid_api_key",
    "message": "The API key provided is not valid or has been revoked."
  }
}

Common code values on 401 are missing_authorization_header, malformed_authorization_header, invalid_api_key, and revoked_api_key. On 403 you will see line_not_authorized, channel_not_enabled, and account_suspended. Neither status is retryable. Retrying a 401 or 403 with the same key produces the same result, so treat both as fatal in your queue: stop the job, alert someone, and fix the key or the permission. Reserve retries for 429 and 5xx.

Debugging checklist

If a request is failing auth, walk this list in order:

Is the header spelled Authorization with the word Bearer and a single space before the key?
Did your shell or config file add quotes, a trailing newline, or a line break inside the key?
Does the key in your environment match a key listed as active in the dashboard?
Did the environment variable actually load? Print its length, never its value.
Is the request hitting https://api.bluereacher.com/functions/v1/, on HTTPS, with no redirect stripping the header?

If all five check out and you still get a 401, create a fresh key and test it with the curl command above.

Getting started

Integrations

Platform

API key format

Where keys come from

Sending the key

Verify a key

Authenticated request in JavaScript

Authenticated request in Python

Keeping keys safe

Rotating a key

401 versus 403

Debugging checklist

​API key format

​Where keys come from

​Sending the key

​Verify a key

​Authenticated request in JavaScript

​Authenticated request in Python

​Keeping keys safe

​Rotating a key

​401 versus 403

​Debugging checklist

API key format

Where keys come from

Sending the key

Verify a key

Authenticated request in JavaScript

Authenticated request in Python

Keeping keys safe

Rotating a key

401 versus 403

Debugging checklist