Authentication
How to authenticate with the Beetles API using JWT tokens and API keys.
Authentication
Beetles uses JWT Bearer tokens for all API requests. You can obtain a token in two ways:
1. Login (Interactive)
For dashboard and development use:
curl -X POST http://localhost:8080/v1/auth/login \
-H "Content-Type: application/json" \
-d '{ "email": "[email protected]", "password": "your-password" }'{
"token": "eyJhbGciOiJIUzI1NiIs...",
"user": { "id": "...", "email": "[email protected]" }
}Tokens expire after 24 hours.
2. API Key Login (Programmatic)
For server-to-server integrations, create an API key and use it to authenticate:
Step 1: Create an API Key
curl -X POST http://localhost:8080/v1/api-keys \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Beetles-Workspace-Id: YOUR_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{ "label": "Production Backend" }'{
"id": "...",
"label": "Production Backend",
"key": "btl_live_abc123..."
}The raw API key is returned only once. Store it securely — you cannot retrieve it later.
Step 2: Login with API Key
curl -X POST http://localhost:8080/v1/auth/login \
-H "Content-Type: application/json" \
-d '{ "api_key": "btl_live_abc123..." }'{ "token": "eyJhbGciOiJIUzI1NiIs..." }Using the Token
Include the JWT in the Authorization header of every request:
curl http://localhost:8080/v1/ledgers \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Beetles-Workspace-Id: YOUR_WORKSPACE_ID"Required Headers
| Header | Required | Description |
|---|---|---|
Authorization | Always | Bearer <jwt_token> |
Beetles-Workspace-Id | For workspace-scoped routes | UUID of the active workspace |
Content-Type | For POST/PUT | application/json |
Auth endpoints (/auth/signup, /auth/login) do not require the Authorization or Beetles-Workspace-Id headers.