Authentication
The adaptlive API uses Bearer token authentication. All requests must include a valid API key in the Authorization header.
API keys
Keys are scoped to your organization and authorize /api/v1 traffic. Mint and revoke from the developer portal at /portal/api-keys. Format: ak_<env>_<32 base32 chars> where <env> is live or test. We store only a SHA-256 hash plus a display-only prefix + last-4 — the full secret is shown once at mint time and is unrecoverable.
Key Types
ak_live_...Production keys with full access. Use in your production environment for real data operations.
ak_test_...Sandbox keys for development. Access synthetic test data without affecting production records.
Making Authenticated Requests
Include your API key in the Authorization header using the Bearer scheme.
curl https://adaptlive.app/api/v1/work-records \
-H "Authorization: Bearer ak_live_XXXXXXXXXXXXXXXXXXXXXXXXXX"// TypeScript
const response = await fetch("https://adaptlive.app/api/v1/work-records", {
headers: {
"Authorization": `Bearer ${process.env.ADAPT_API_KEY}`,
"Content-Type": "application/json",
},
});Never expose keys client-side
API keys should only be used in server-side code. Never include them in frontend JavaScript, mobile apps, or public repositories.
Key management
| Action | Description |
|---|---|
| Create | Mint a fresh key from /portal/api-keys. Pick the scope (READ / WRITE / ADMIN). The full secret is shown once. |
| Rotate | Mint a replacement, cut traffic over to it, then revoke the old one. Multiple active keys are allowed per org, so this is zero-downtime. |
| Revoke | Mark a key as revoked. Within a minute every request using it returns 401 unauthorized. |
Keys you no longer trust should be revoked the moment you suspect a leak — there's no penalty for rotating frequently.
API Key Scopes
| Scope | Permissions |
|---|---|
| READ | List and retrieve records. Cannot create, update, or delete. |
| WRITE | Full CRUD access to records. Cannot manage org settings or users. |
| ADMIN | Full access including organization management. Owner-only scope. |
Authentication Errors
No API key provided or the key is invalid/expired.
{
"error": {
"code": "unauthorized",
"message": "Invalid or missing API key"
}
}The API key is valid but lacks permission for this operation (e.g., READ key attempting a POST).
{
"error": {
"code": "forbidden",
"message": "Insufficient permissions for this operation"
}
}Rate limits
adaptlive reserves the right to throttle abusive callers. Specific quotas aren't published today and may be tightened without notice — write defensively against 429 and back off when you see one. If you expect sustained high volume, email developers@adaptlive.app before launch.
Throttled responses come back as 429 Too Many Requests with this body shape:
{
"error": {
"code": "rate_limited",
"message": "Rate limit exceeded — retry after the Retry-After window."
},
"meta": { "requestId": "..." }
}Headers you can rely on when present:
Retry-After: 12 # seconds until the next attempt is permitted
X-RateLimit-Limit: <int> # the bucket capacity
X-RateLimit-Remaining: <int> # tokens left in this window
X-RateLimit-Reset: <unix> # unix-second when the bucket fully refillsRecommended retry strategy: honor Retry-Afterexactly on the first failure. If a retry also fails, switch to exponential backoff with jitter capped at 60 seconds. Don't hammer.