Authentication
The API uses bearer API keys. Keys belong to a company, act with the permissions of the user who created them, and can be revoked instantly.
Bearer keys
Authorization: Bearer airo_sk_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX- Create and revoke keys in the portal under Connect AI. Only owners and admins can manage keys.
- Keys are shown once and stored only as a hash. If a key leaks, revoke it and create another.
- Keys expire (90 days by default) and every call is logged with the key, tool and outcome, never with your payload.
Scopes
| Scope | Allows |
|---|---|
| imports.write | Submit orders and vehicles (used by POST /v1/optimizations) |
| jobs.write | Create and cancel optimizations, manage webhooks |
| jobs.read | Read optimizations, results and exports |
| imports.read | List imports (portal and MCP) |
A key can never do more than the role of the user who created it. If that user is downgraded, the key shrinks immediately. Create a read-only key (jobs.read) for dashboards.
Rate limits
- 60 requests per minute per key, 240 per company and 180 per IP address.
- Exceeding a limit returns 429 with the code rate_limited. Back off and retry.
- Optimizations also respect your plan: at most two active optimizations per company at once.
Errors you may see
| Status | Code | Meaning |
|---|---|---|
| 401 | not_authenticated | No Authorization header |
| 401 | invalid_api_key | Unknown, expired or revoked key |
| 403 | insufficient_scope | The key lacks the scope named in the message |
| 429 | rate_limited | Too many requests |