Authentication
Bearer API keys — scoping, failure modes, and zero-downtime rotation.
Every request carries your API key as a Bearer token:
Authorization: Bearer fr8_live_your_key_hereThere is no other authentication mechanism — no cookies, no sessions, no OAuth flow.
Scope
A key belongs to exactly one customer account. Requests authenticated with your key can only ever return loads that belong to your company — this is enforced structurally on our side, not by a filter you pass. There is no parameter that widens scope.
Failure modes
| Situation | Response |
|---|---|
No Authorization header | 401 {"error": "Unauthorized"} |
Malformed header (not Bearer <token>) | 401 {"error": "Unauthorized"} |
| Unknown key | 401 {"error": "Unauthorized"} |
| Revoked key | 401 {"error": "Unauthorized"} |
All four are deliberately identical — a 401 never tells you (or
anyone else) whether a key exists or used to exist. If you get a
persistent 401 with a key you believe is valid, contact your account
contact rather than debugging the response.
Key handling
- Store the key in a secret manager; never commit it to source control. It's shown exactly once at creation and cannot be recovered — only replaced.
- Don't put the key in URLs or logs. The
Authorizationheader is the only place it belongs. - Treat a suspected leak as a rotation: ask for a new key, cut over, then have the old one revoked.
Rotation without downtime
Your account can hold two active keys at once, specifically so you can rotate with zero downtime:
- Ask your account contact for a second key.
- Deploy your integration with the new key.
- Confirm traffic works, then ask us to revoke the old key.
Revocation is immediate: the old key starts returning 401 on its next
request.