Authentication
Bearer tokens, scopes, and how API keys secure your workspace.
All API requests are authenticated using bearer tokens in the standard Authorization header. Tokens use the ax_ prefix and are cryptographically signed, so forged or malformed tokens are rejected before they reach the database.
Authorization: Bearer ax_...Tokens are bearer instruments: anyone with the token string can use it. Store them the way you would store a password. Only a salted digest is stored server-side, so even a database breach does not reveal usable tokens.
🔐 Scopes
Tokens carry one of two scope levels, determined at creation time:
| Scope | Description |
|---|---|
| Server | Global access across all workspaces. Used for administrative operations and workspace management. |
| Workspace | Scoped to a single workspace. Can access the documents, jobs and keys of that workspace only. |
A workspace-scoped token is bound to its workspace at creation and cannot be moved or escalated. Server-scoped tokens are typically reserved for platform administration and are not issued through the standard key creation flow.
Selecting the Workspace
Paths never name the workspace: a workspace-scoped token always acts on its own. A server-scoped token belongs to no workspace, so it names one in the X-Workspace-Id header on every workspace route (/documents, /parsings, /keys, ...):
X-Workspace-Id: 018f8e024b2a7c3d9e1f0a2b3c4d5e6fWithout the header a server-scoped token gets 400. A workspace-scoped token may omit it; if it sends another workspace, it gets 403. Administrative routes under /admin ignore the header.
🛠️ Key Management
API keys are managed at the workspace level. For a detailed technical reference of every field and parameter, see the API Keys reference.
Create an API Key
Issue a new bearer token for a workspace. You can optionally set a name and an expiration date.
curl -X POST "https://api.axelered.com/v1/keys" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Production Key",
"expires_in": "90d"
}'The response includes the full token string in the secret field. This is the only time the token is returned in full: store it securely. The token cannot be retrieved again.
List, Read & Revoke
To manage existing keys, use the following endpoints:
- List API Keys: Retrieve all active keys within a workspace.
- Delete API Key: Immediately revoke a key. It stops working the moment deletion completes.