Authentication
Authenticate public API requests with bearer tokens.
The public API uses bearer token authentication.
Send requests from a trusted backend, job runner, integration platform, or private automation script. Do not send bearer tokens from browser code or public client apps.
Request Header
Send the API token in the Authorization header:
curl "$AGILED_API_BASE_URL/public/v1/me" \
-H "Authorization: Bearer $AGILED_API_TOKEN"The token must be the complete value shown when the API key is created.
Store the token as a secret named something like AGILED_API_TOKEN. Avoid
hard-coding it in source files, shell history, notebooks, or shared examples.
Token Scope
Each key belongs to one organization scope. Requests can only access records in that workspace, and the token abilities control whether a resource can be read or written.
If you manage multiple organizations, create separate keys for each workspace and label them clearly in the external system.
Presets
Agiled currently provides:
- Full access: read and write abilities across supported public API resources.
- Read only: read abilities across supported public API resources.
Failed Authentication
Requests without a valid token return:
{ "error": "Unauthorized." }Requests with a valid token that lacks the required ability return:
{ "error": "Forbidden." }Authentication Checklist
- Confirm the API base URL belongs to the intended environment.
- Confirm the token belongs to the intended workspace.
- Send the
Authorization: Bearerheader exactly once. - Test
/public/v1/mebefore making write requests. - Rotate tokens on a schedule and after suspected exposure.
Troubleshooting
If you receive Unauthorized, check missing header, extra spaces, copied token
truncation, revoked key, or expired key.
If you receive Forbidden, the token is valid but does not have the required
ability for that endpoint.
Token Handling Rules
Treat API tokens like passwords. Store them in a secret manager, rotate them when teammates leave or vendors change, and use separate tokens for production, staging, and local development.
If a token is exposed in logs, source control, chat, or a support ticket, revoke it and create a replacement. Do not wait for an error before rotating a known exposed token.
Access Review
Review API keys on the same schedule as other privileged access. Confirm each key still has an owner, a purpose, and the smallest ability set needed for the integration.
Revoke keys for retired vendors, old migrations, abandoned scripts, and teammates who no longer maintain the integration.