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 for the following 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

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.

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.