Getting started

Authentication

Every request to the BlueReplies API needs an API key, passed as the x-api-key header. Keys are scoped to one customer and can be in either sandbox or production mode.

The header

curl https://api.bluereplies.com/v1/messages \
  -H 'x-api-key: sk_sandbox_…'

We support a few SDK conventions too — see the SDKs page.

Key prefixes

The first segment of every API key tells you (and us) which mode it operates in. Sandbox and production share the same endpoint base URL — the prefix is the signal.

Field	Type	Description
`sk_sandbox_…`	string	Sandbox key. Outbound sends limited to your activated phone + verified contacts. Free, auto-issued on signup activation. e.g. `sk_sandbox_a4f2k9bce7g3…`
`sk_live_…`	string	Production key. Full access to your assigned line(s). Issued after we promote your account from sandbox. e.g. `sk_live_pq3z…`

Security best practices

Never commit keys to source control. Use environment variables or a secret manager.
Never use keys in client-side code (browser JS, mobile apps). All API calls must originate from a server.
Use the smallest scope available — sandbox keys for dev, production keys only for live traffic.
Rotate immediately if a key leaks. Revoking a key takes effect in < 1s.
Restrict by IP on your production account (request via support).

If you suspect a leak

Go to Dashboard → API keys and click Revoke. The key stops working within 1 second. Generate a new one, deploy it, and audit your access logs for unexpected requests.

What happens with a bad key

Missing or invalid keys return 401 Unauthorized:

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API key is missing, revoked, or invalid."
  }
}

If your account is suspended or pending, you'll see a 403 Forbidden with a more specific code instead.

Initializing the SDK

import { BlueReplies } from 'blueapi';

const client = new BlueReplies({
  apiKey: process.env.BLUEREPLIES_KEY,
  // Optional:
  // timeout: 30_000,
  // baseUrl: 'https://api.bluereplies.com/v1',  // for self-hosted / staging
});