Skip to main content

​
Overview

The Boomerang Developer API uses bearer tokens. Tokens are generated in the dashboard, sent on each request in an Authorization header, and expire after a fixed period. This page covers:
  • How to create and view tokens
  • How to send tokens with requests
  • Expiry, rotation, and revocation
  • Security and logging expectations
For behavioural rules and acceptable use, see the Usage Guidelines.

​
Token model

  • Authentication uses bearer tokens.
  • Tokens are scoped to a single server.
  • Any request to a protected endpoint must include a valid token for that server.
  • All tokens currently carry the same read-only permission set.
Treat each token as you would a password for that server’s API access.

​
Creating and viewing tokens

Tokens are managed per server in the Boomerang dashboard. Anyone with dashboard access to a server can manage that server’s tokens.
1

Open the server dashboard

Select the server you want to integrate with in the Boomerang dashboard.
2

Go to Developer

Use the Developer item in the side menu to open the token management view.
3

Generate a new token

Choose Generate a new token and provide a clear name that indicates the intended use (for example, “Prod job runner” or “Staging admin tool”).
4

Set an expiry

Choose a fixed expiry interval (for example, 7, 30, 90, or 120 days). Shorter lifetimes are recommended for higher-risk or internet-exposed integrations.
5

Copy and store the token

Confirm to create the token. The full token value is shown once. Copy it immediately into a secure .
After creation:
  • The dashboard shows only a truncated preview of the token.
  • Metadata such as name, expiry, and last-used time are visible for monitoring and clean-up.
  • The full token value cannot be retrieved again.

​
Token expiry and rotation

All tokens must have a fixed lifetime set at creation. Non-expiring tokens are not supported. When creating a token, you select one of the predefined expiry options (for example, 7 days, 30 days, 90 days, or 120 days). Use shorter intervals for higher-risk or internet-facing integrations, and longer intervals only where operationally necessary. You are responsible for:
  • Monitoring token expiry and renewing or rotating tokens before they expire.
  • Removing tokens that are no longer required.
  • Ensuring your systems handle token expiry without unsafe side effects.
Tokens can be:
  • Rotated by creating a replacement token (with a new name or updated expiry), updating your systems to use it, then deleting the old token.
  • Revoked immediately by disabling or deleting them in the dashboard (or via supported API calls).
Rotation should be performed without downtime by overlapping old and new tokens until all clients are updated.

​
Using tokens in requests

All authenticated requests must include the token as a bearer token in the Authorization header. Use the following format: 
Authorization: Bearer YOUR_TOKEN_HERE
Requirements:
  • The header name must be exactly Authorization.
  • The scheme must be exactly Bearer followed by a single space and the token value.
  • Tokens should only be sent from trusted back-end services, not from browsers, mobile apps, or other untrusted client environments.

​
Security expectations

Minimum expectations for token security:
  • Storage Store tokens only in secure . Do not store tokens in source control, shared documents, screenshots, or chat logs.
  • Exposure Do not embed tokens in client-side JavaScript, public repositories, or downloadable tools. Any environment where untrusted users can see or intercept requests must not contain raw tokens.
  • Access control Limit dashboard access and token management to trusted individuals who need it for integration work.
  • Change handling Rotate or revoke tokens immediately if:
    • Compromise is suspected; or
    • Anyone who previously had access to a token no longer should.
For security questions or to report suspected abuse, contact [email protected].

​
Authentication failures

Authentication-related failures follow these patterns:
  • Missing or malformed header No Authorization header, or a header that does not follow the expected Bearer format.
  • Invalid, expired, or revoked token The token cannot be validated, has passed its expiry, or has been revoked in the dashboard.
  • Authenticated but not permitted The token is valid but cannot access the requested resource for that server.
Your integration should:
  • Log authentication failures separately from other errors.
  • Avoid aggressive retries on authentication errors; verify configuration and token status first.
  • Fail safely, without exposing sensitive implementation details in user-facing messages.
Detailed status codes and error formats are documented in the API reference.

​
Monitoring and ownership

Boomerang logs token usage and may review patterns to protect stability and user safety. Server owners and maintainers are expected to:
  • Periodically review the token list for each server.
  • Remove unused, obsolete, or risky tokens.
  • Ensure that only trusted people retain dashboard access and access to that store or use tokens.
Boomerang may throttle, restrict, or revoke token access where usage appears abusive or inconsistent with the Usage Guidelines.