API Authentication

Access tokens authenticate your requests to the Broadcast API. Each token can be configured with specific permissions to control what actions it can perform.

How Access Tokens Work

Access tokens are API keys that:

• Authenticate requests to the Broadcast API
• Control access through granular permissions
• Can be created, refreshed, and revoked at any time
• Are scoped to a specific broadcast channel

When you install Broadcast, a default access token is created with transactional email permissions. You can create additional tokens with different permission sets for various use cases.

Creating an Access Token

To create a new access token:

1. Navigate to Access Tokens in the sidebar
2. Click New Token
3. Enter a descriptive name (e.g., “Production API”, “Transactional emails”)
4. Select the permissions this token needs
5. Click Create token

Token Permissions

Each resource type has two permission levels:

You can set permissions independently for each of these eleven resources:

Best practice: Create tokens with only the permissions they need. A token for sending transactional emails doesn’t need access to broadcasts or segments.

Quick Permission Selection

When creating or editing a token, use the quick selection buttons:

• All - Enable all read and write permissions
• Read only - Enable only read permissions for all resources
• None - Disable all permissions

Admin API Tokens

The tokens described above belong to one channel and can only ever see that channel. When an integration has to reach several channels, for example a provisioning script or a reporting job that runs across an installation, use an admin API token instead.

Create them under Application → Admin API Tokens.

Admin tokens carry the same eleven permissions as channel tokens. What differs is scope, and one requirement that follows from it.

Every channel-scoped request needs broadcast_channel_id

Because an admin token is not tied to a channel, it has to be told which channel each request is for. Send broadcast_channel_id as a query parameter:

curl -X GET "https://your-broadcast-domain.com/api/v1/subscribers?broadcast_channel_id=3" \
  -H "Authorization: Bearer YOUR_ADMIN_API_TOKEN" \
  -H "Content-Type: application/json"

Omit it and the request fails immediately:

{
  "error": "broadcast_channel_id is required for admin API tokens"
}

That is a 400 Bad Request. A channel id that does not exist returns 404 with Broadcast channel not found.

When to use which

Every request made with an admin token is written to the application log with the token id and the channel it accessed, so there is an audit trail. See Monitoring and Logs.

Using an Access Token

Include your access token in the Authorization header of every API request:

Authorization: Bearer YOUR_ACCESS_TOKEN

Example Request

curl -X GET "https://your-broadcast-instance.com/api/v1/subscribers" \
  -H "Authorization: Bearer 8779fc02262b9701fe0fff82f1eec8b9" \
  -H "Content-Type: application/json"

Error Responses

Dates and Times

Send every date and timestamp as ISO 8601, and expect the same format back:

Either form is accepted wherever a date or timestamp is expected: a bare date is read as midnight, and a timestamp given to a date parameter contributes its date part. Unix seconds work too. A value carrying no timezone is read in your instance’s configured timezone.

Locale date formats are not part of the API. This is deliberate rather than fussy: 01/02/2026 is the 1st of February in most of the world and the 2nd of January in the United States, and nothing in the request says which one you meant. An API that guesses hands a different month’s data to half its callers with no error to signal it, so Broadcast asks for the unambiguous form instead.

What happens to a value that cannot be read depends on what the parameter does, and each endpoint’s reference page says which applies:

• A parameter that changes data rejects the request, so nothing is written from a value the server had to guess at.
• A parameter that filters a list may instead ignore the value and answer the rest of the query, reporting a parameter_ignored entry in the response’s warnings array. Check that array rather than assuming every filter you sent was applied: an ignored filter returns more rows than you asked for, not fewer. See API Response Warnings.

Rate Limiting

The API enforces rate limiting to protect against abuse and ensure fair usage for all users.

Limits

Each API token has its own independent rate limit. Using multiple tokens allows for higher overall throughput if needed.

You can customize the rate limit by setting the API_RATE_LIMIT environment variable (requests per minute). For example, to set it to 600 requests per minute:

API_RATE_LIMIT=600

Rate Limit Headers

Every API response includes rate limit headers so you can monitor your usage:

When you receive a 429 Too Many Requests response, the following additional header is included:

Example Rate Limited Response

{
  "error": "Rate limit exceeded. Please retry later."
}

Handling Rate Limits

When you receive a 429 response:

1. Check the Retry-After header for how long to wait
2. Implement exponential backoff in your retry logic
3. Consider batching requests where possible
4. Use multiple tokens if you need higher throughput

# Example retry logic
def make_api_request
  response = api_call

  if response.status == 429
    retry_after = response.headers['Retry-After'].to_i
    sleep(retry_after)
    retry
  end

  response
end

Viewing Token Details

Click any token in the list to view its details:

The detail view shows:

• Full token value - Click Copy to copy to clipboard
• Permissions - What this token can access
• Usage stats - When the token was created and last used

Managing Access Tokens

Refreshing Tokens

You can regenerate a token’s value while keeping its permissions:

1. Click on the token you want to refresh
2. Click Refresh
3. Confirm the refresh
4. Copy the new token value

Warning: Refreshing a token immediately invalidates the old value. Update all applications using this token before refreshing.

Editing Permissions

To change a token’s permissions:

1. Click on the token
2. Click Edit permissions
3. Update the permission checkboxes
4. Click Update token

Deleting Tokens

To revoke a token permanently:

1. Click the delete button (trash icon) next to the token
2. Confirm the deletion

Deleted tokens cannot be recovered. Any applications using the deleted token will immediately lose access.

OpenAPI Specification

Your installation serves a machine-readable OpenAPI 3.1 description of its own API:

GET /api/v1/openapi

It needs a token like any other endpoint, and returns YAML:

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://your-broadcast-domain.com/api/v1/openapi > broadcast-api.yaml

/api/v1/openapi.yaml works identically, for tooling that insists on a file extension.

Use it to generate a client library, import the API into Postman or Insomnia, or point an API explorer at it. The document names your own installation as its server, so requests work as soon as you add a token, with no editing.

Security Best Practices

1. Use descriptive names - Make it easy to identify what each token is used for
2. Minimize permissions - Only grant the permissions each token actually needs
3. Rotate regularly - Refresh tokens periodically, especially after team changes
4. Never commit tokens - Keep tokens out of version control and public repositories
5. Use environment variables - Store tokens in environment variables, not in code
6. Monitor usage - Check the “last used” timestamp to identify unused tokens
7. Revoke unused tokens - Delete tokens that are no longer needed

Common Use Cases

Transactional Emails Only

For sending transactional emails (password resets, receipts, etc.): - Transactional Emails: Read + Write

Subscriber Management Integration

For syncing subscribers from another system: - Subscribers: Read + Write - Segments: Read (optional, to assign subscribers to segments)

Read-Only Dashboard

For a reporting dashboard that displays metrics: - Broadcasts: Read - Subscribers: Read - Sequences: Read

Full API Access

For admin tools that need complete access: - All resources: Read + Write

Note: Only use full access tokens when absolutely necessary.