Skip to main content
The BOOM API uses JWT (JSON Web Token) authentication to secure endpoints. You must obtain an access token before making requests to protected resources.

​
Obtain an access token

curl -X POST http://localhost:4000/auth \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=your_username&password=your_password"

​
Request

​
username
string
required
Your BOOM username
​
password
string
required
Your BOOM password

​
Response

​
access_token
string
JWT access token for authenticating requests
​
token_type
string
Token type, always Bearer
​
expires_in
number
Token expiration time in seconds (default: 604800 seconds / 7 days)

​
Using the access token

Include the access token in the Authorization header of your requests: 
curl http://localhost:4000/filters \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Error responses

​
Invalid credentials

If the username or password is incorrect, you’ll receive a 401 Unauthorized response: 
{
  "error": "invalid_client",
  "error_description": "Invalid username or password"
}

​
Invalid request

For malformed requests, you’ll receive a 400 Bad Request response: 
{
  "error": "invalid_request",
  "error_description": "Error details"
}

​
Token expiration

JWT tokens expire after 7 days by default. This can be configured in config.yaml: 
api:
  auth:
    token_expiration: 604800  # Expiration in seconds
When a token expires, you’ll receive a 401 Unauthorized response. Simply request a new token using the authentication endpoint.

​
Configuration

Authentication settings are configured via environment variables:
​
BOOM_API__AUTH__SECRET_KEY
string
required
Secret key for signing JWT tokens. Must be set for security.
​
BOOM_API__AUTH__ADMIN_USERNAME
string
Username for the default admin account (default: admin)
​
BOOM_API__AUTH__ADMIN_PASSWORD
string
required
Password for the default admin account. Must be set.
​
BOOM_API__AUTH__ADMIN_EMAIL
string
Email for the default admin account (default: [email protected])

​
Security best practices

Never commit your secret key or credentials to version control. Always use environment variables.
  • Store tokens securely and never expose them in client-side code
  • Use HTTPS in production to encrypt token transmission
  • Rotate your secret key periodically
  • Set a strong admin password
  • Request new tokens before they expire to maintain uninterrupted access

Build docs developers (and LLMs) love

Get started for freeTalk to us