API Authentication

The Broadcast API lets you manage subscribers, send emails, and access your data programmatically. Every API request requires a valid API token for authentication. This guide covers how to create tokens, configure permissions, make authenticated requests, and handle errors.

Overview

Broadcast uses Bearer token authentication. You create API tokens from your dashboard, then include the token in the Authorization header of every HTTP request. Tokens are scoped with permissions so you can control exactly what each integration is allowed to do.

Creating an API Token

1. Go to Settings > API Tokens in your Broadcast dashboard
2. Click Create Token
3. Give your token a descriptive name that identifies its purpose (e.g., “Website signup integration”, “CRM sync”, “Analytics dashboard”)
4. Configure the token’s permissions (see below)
5. Click Create
6. Copy the token immediately – for security, the full token is only displayed once at creation time. If you lose it, you’ll need to generate a new one.

Store the token somewhere safe, like a password manager or your application’s environment variables, before closing the creation dialog.

Token Permissions

API tokens support granular permissions so you can follow the principle of least privilege. When creating or editing a token, you can configure two levels of access:

Read Permissions

Read access allows the token to retrieve data without modifying anything:

• List and view subscribers and their details
• View broadcasts and their analytics
• List sequences and their configuration
• View segments and their rules
• Access email server configurations
• Retrieve opt-in form details

Write Permissions

Write access allows the token to create, update, and delete resources:

• Add, update, and remove subscribers
• Create and send broadcasts
• Manage sequences and enrollment
• Create and modify segments
• Configure email servers
• Send transactional emails

You can grant read-only access, write-only access, or both. For integrations that only need to pull data (like reporting dashboards), a read-only token reduces your security surface. For integrations that push data in (like a signup form backend), write access is what you need.

Base URL

All API requests for Broadcast use the following base URL:

https://app.sendbroadcast.com/api/v1

Every endpoint documented in the API reference is relative to this base URL. For example, the subscribers endpoint is:

https://app.sendbroadcast.com/api/v1/subscribers

Using Your Token

Include your API token in the Authorization header using the Bearer scheme:

curl -X GET "https://app.sendbroadcast.com/api/v1/subscribers" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Every request must include both headers:

• Authorization: Bearer YOUR_API_TOKEN – authenticates the request
• Content-Type: application/json – tells the API you’re sending and expecting JSON

Your First API Call

Here’s a quick recipe to verify your token works. This request lists subscribers in your broadcast channel:

curl -X GET "https://app.sendbroadcast.com/api/v1/subscribers" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

A successful response returns a JSON array of subscribers:

{
  "data": [
    {
      "id": 1,
      "email": "[email protected]",
      "first_name": "Jane",
      "last_name": "Smith",
      "status": "active",
      "created_at": "2026-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 5,
    "total_count": 247
  }
}

If you get a 200 OK response with data, your token is working correctly and you’re ready to build your integration.

Security Best Practices

API tokens are the keys to your Broadcast account. Treat them with the same care as passwords.

Use Environment Variables

Never hardcode tokens in your source code. Store them in environment variables:

# Set the variable in your environment
export BROADCAST_API_TOKEN="your_token_here"

# Reference it in your API calls
curl -X GET "https://app.sendbroadcast.com/api/v1/subscribers" \
  -H "Authorization: Bearer $BROADCAST_API_TOKEN" \
  -H "Content-Type: application/json"

Never Commit Tokens to Version Control

Add your environment files to .gitignore and never commit files containing tokens. If a token is accidentally committed, rotate it immediately – even if the repository is private.

Rotate Tokens Periodically

Regular rotation limits the window of exposure if a token is compromised. We recommend rotating production tokens every 90 days, or immediately if you suspect unauthorized access.

Use HTTPS Only

All API requests must be made over HTTPS. Broadcast rejects plain HTTP requests to protect your token from being intercepted in transit.

Scope Tokens Narrowly

Create separate tokens for separate integrations. If your website signup form only needs to add subscribers, give that token write access to subscribers only. If your analytics dashboard only reads data, give it read-only access. This way, a compromised token has limited impact.

Token Rotation

To rotate a token:

1. Go to Settings > API Tokens
2. Find the token you want to rotate
3. Click Refresh to generate a new token value
4. Copy the new token immediately
5. Update your application or integration with the new token
6. Verify the integration works with the new token

The old token value stops working as soon as you refresh, so update your applications promptly to avoid downtime.

Error Responses

401 Unauthorized

Returned when the token is missing, malformed, or invalid.

{
  "error": "Unauthorized",
  "message": "Invalid or missing API token"
}

Common causes:

• The Authorization header is missing from the request
• The token was copied incorrectly (check for extra spaces or truncation)
• The token has been refreshed or deleted

403 Forbidden

Returned when the token is valid but lacks permission for the requested action.

{
  "error": "Forbidden",
  "message": "Insufficient permissions for this action"
}

Common causes:

• A read-only token is being used for a write operation (e.g., creating a subscriber)
• The token doesn’t have access to the specific resource type
• The requested broadcast channel is not accessible with this token

Rate Limiting

To ensure platform stability, API requests are rate limited:

• 100 requests per minute for general endpoints (listing, reading, creating, updating)
• 10 requests per minute for sending operations (broadcasts, transactional emails)

Rate limit information is included in every API response via headers:

When you exceed the rate limit, you’ll receive a 429 Too Many Requests response. Wait until the reset time before retrying. For high-throughput integrations, implement exponential backoff in your client code.

Next Steps

Now that you’re authenticated, explore what you can build:

• Subscribers API – add, update, list, and manage subscribers programmatically
• Broadcasts API – create and send campaigns via the API
• Transactional Email API – send one-off emails triggered by events in your application

Need help with your integration? Contact our support team and we’ll help you get connected.