Authentication
All API endpoints require authentication except POST /api/v1/auth/login.
Bearer token (recommended)
Obtain a short-lived JWT by posting your credentials to the login endpoint, then include it in theAuthorization header on every request.
# Step 1 — log in
curl -X POST /api/v1/auth/login \
-H 'Content-Type: application/json' \
-d '{"email":"you@example.com","password":"••••••••"}'
# Response
{
"data": { "token": "eyJhbGciOiJ...", "user": { ... } }
}
# Step 2 — use the token
curl /api/v1/workspaces \
-H 'Authorization: Bearer eyJhbGciOiJ...'
Session cookie
Browser-based requests from the same origin are authenticated automatically via thepayload-token session cookie set at login. No additional headers are needed from within the web app.
Token lifetime and refresh
| Property | Value |
|---|---|
| Algorithm | HS256 (HMAC-SHA256) |
| Lifetime | 2 hours |
| Refresh | Re-authenticate via POST /api/v1/auth/login |
| Revoke | POST /api/v1/auth/logout |
Error responses
401
Unauthorized
Token is missing, malformed, or expired. Re-authenticate.
403
Forbidden
Token is valid but the user lacks permission for this resource.