Authentication
Two ways to authenticate: user JWT tokens for dashboards, and API keys for server-to-server calls.
User auth
JWT
Bearer token
Server auth
API Key
ak_ + as_
JWT expiry
7 days
Configurable
Signature
SHA-256
HMAC
Overview
Pick the right auth for the job
There are two authentication mechanisms. Use the right one for the context — they're not interchangeable.
User JWT
For logged-in users
- Issued on login
- Represents a single user session
- Expires after 7 days
- Full tenant + role access
API Key
For server integrations
- Created by admins
- Scoped to specific permissions
- Long-lived (up to 1 year)
- No user context
User JWT authentication
For logged-in dashboard users
When a user logs in, our auth service returns a JWT token. Include it on every request in the Authorization header.
curl -X POST https://api.yourapp.com/api/auth/login \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"password": "your_password"
}'{
"success": true,
"data": {
"user": {
"id": "507f1f77bcf86cd799439011",
"name": "John Doe",
"email": "john@example.com",
"role": "ADMIN",
"tenant": {
"id": "507f1f77bcf86cd799439012",
"name": "Acme Corp",
"type": "OFFICE"
}
},
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
}Use the token on every request
curl https://api.yourapp.com/api/users \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."Tokens expire after 7 days by default
Verified on every request
Contains tenantId + role
API Key authentication
For server-to-server integrations
API keys are long-lived credentials created by tenant admins. They're scoped to specific permissions and don't represent a user — only the tenant.
Settings → API Keys → Generate New Key
The secret is only shown once — save it immediately
Send in Authorization or X-API-Key header
Two header formats
Authorization: Bearer ak_3f8a9b2c4d5e6f7a8b9c0d1e2f3a4b5c
# or
X-API-Key: ak_3f8a9b2c4d5e6f7a8b9c0d1e2f3a4b5c| Value | Prefix | Use |
|---|---|---|
| key | ak_ | Public — sent on every request |
| secret | as_ | Private — signs webhook payloads |
Auth headers reference
What to send and when
| Header | Used with | Format |
|---|---|---|
| Authorization | JWT or API Key | Bearer <token> |
| X-API-Key | API Key only | ak_... |
| X-API-Secret | API Key (optional) | as_... |
Full request with JWT
const res = await fetch('https://api.yourapp.com/api/users', {
method: 'GET',
headers: {
Authorization: `Bearer ${jwtToken}`,
'Content-Type': 'application/json',
},
});Full request with API key
const res = await fetch('https://api.yourapp.com/api/v1/public/users', {
method: 'GET',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
});Best practices
Do's and don'ts
- Store tokens in httpOnly cookies or memory
- Use environment variables for API keys
- Rotate keys on a schedule
- Give API keys minimum permissions
- Use HTTPS only
- Commit API keys to git
- Expose secrets in client-side code
- Use API keys in browser apps
- Share keys between applications
- Reuse a single key for all integrations
Next steps
Continue building
Need help with auth?
Reach out with your tenant ID and the failing request (redact secrets).