Authentication

How to obtain and use JWT tokens with the Beacon Tower API.

Overview

Beacon Tower uses OAuth 2.0 Resource Owner Password Credentials (ROPC) flow for machine-to-machine authentication and interactive login. The platform supports two authentication methods:

• Bearer Token (JWT) — Short-lived access tokens obtained via username/password authentication
• API Key — Long-lived credentials for service accounts and integrations

Requesting a Token

To authenticate and obtain an access token, send a POST request to the /auth/ropc endpoint:

curl -X POST https://api.beacontower.ai/auth/ropc \
  -H "Content-Type: application/json" \
  -d '{"username": "user@example.com", "password": "your-password"}'

Request Body

{
  "username": "your-username",
  "password": "your-password"
}

Response

On successful authentication, the API returns an access token:

{
  "accessToken": "eyJhbGciOiJSUzI1NiIs..."
}

Error Responses

Status Code	Description
400	Missing or invalid credentials in request body
401	Invalid username or password
404	Authentication route not found
500	Internal server error

Using the Token

Include the access token in the Authorization header of all API requests:

curl https://api.beacontower.ai/assets \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Token Lifetime: Access tokens have a limited lifetime. When a token expires, you will receive a 401 Unauthorized response. Re-authenticate using the /auth/ropc endpoint to obtain a new token.

API Key Authentication

API keys provide an alternative authentication method suitable for service accounts and long-running integrations. Include your API key in the X-API-Key header:

curl https://api.beacontower.ai/assets \
  -H "X-API-Key: your-api-key"

API keys are managed through the platform administration interface. Contact your organization administrator to obtain an API key.

Security Note: API keys are long-lived credentials. Store them securely and never commit them to version control. Consider using environment variables or a secrets management system.

Scopes and Permissions

Access to API endpoints is controlled by a combination of privileges and resource permissions. Users must have both:

1. Organization Privilege — Assigned to the user's organization
2. Resource Permission — View, Manage, or Owner access on specific resources

Available Privileges

Privilege	Description
asset_management	Assets CRUD operations, commands, and properties
dashboard_management	Dashboards CRUD operations
user_management	Users and groups management
tree_management	Node trees and graph operations
model_management	Models, drafts, and binding descriptions
alarm_management	Alarm definitions and status management
organization_management	Organization CRUD operations
provider_management	Providers and provider clients management
notification_management	Notifications and contact groups
firmware_management	Firmware releases and deployments

Each privilege maps to a specific set of API endpoint groups. Attempting to access an endpoint without the required privilege will result in a 403 Forbidden response.

Resource Permissions

Resource-level permissions determine what actions a user can perform on individual resources:

• View — Read-only access
• Manage — Read and update access
• Owner — Full control including deletion and permission management

Next Steps

• Follow the Your First Asset guide for a practical walkthrough of authentication and asset creation
• Explore the API Reference for detailed endpoint documentation
• Review the API Reference for error response formats and troubleshooting