Docs / Authentication

Authentication

Boltly supports two authentication methods: API keys for server-to-server integrations and JWT tokens for user-facing applications.

API Keys

API keys are the recommended way to authenticate programmatic access. Each key is scoped to specific permissions and tied to your organization.

Creating an API key

Go to Settings → Developer Access → API Keys in the dashboard, or use the API:

cURL

curl -X POST https://api.boltly.online/v1/developer-access/api-keys \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My integration",
    "scopes": ["contacts:read", "contacts:write", "inbox:read"]
  }'

The response includes a secret_key starting with sk_live_. This is shown only once — store it securely.

Using an API key

Pass your key in the X-API-Key header:

Header

X-API-Key: sk_live_abc123...

Keys are validated via SHA-256 hash lookup with a two-tier cache (in-memory → Redis → PostgreSQL). Revoked or expired keys return 401.

Scopes

Each API key is assigned one or more scopes that control which endpoints it can access.

contacts:read List and retrieve contacts

contacts:write Create and update contacts

contacts:manage Delete contacts and manage tags

inbox:read Read conversations and messages

inbox:write Send messages and update conversations

broadcasts:read List broadcasts and view metrics

broadcasts:create Create and schedule broadcasts

broadcasts:send Execute and retry broadcasts

templates:read List and retrieve templates

templates:create Create and submit templates

templates:manage Delete templates and sync from Meta

tokens:read List API keys and scopes

tokens:create Create API keys and webhook subscriptions

JWT Tokens

For user-facing applications (like the Boltly dashboard), authentication uses short-lived JWT access tokens with refresh token rotation.

Access token 15-minute expiry, HS256 signed

Refresh token 7-day expiry, rotated on each refresh

Header Authorization: Bearer <access_token>

Login

cURL

curl -X POST https://api.boltly.online/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@company.com",
    "password": "your-password"
  }'

Refresh

cURL

curl -X POST https://api.boltly.online/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{ "refresh_token": "rt_..." }'

Quickstart Webhooks