Authentication

API Keys

All requests require a Bearer token in the Authorization header:

Authorization: Bearer fri_your_key_here

Keys start with fri_ followed by 64 hex characters. Generate keys from your dashboard.

Scopes

Keys can be scoped to specific skills. A scoped key can only call the skills it was created with, providing defense-in-depth if a key is leaked.

Example: A key scoped to rate-lookup and fuel-surcharge can call those two endpoints but will receive a 403 on any other skill.

Scopes are set at key creation time in the dashboard. Create keys without scopes for full tier access.

Rate Limits

Rate limits apply per API key:

When you hit a limit, the API returns 429 Too Many Requests with headers telling you when you can retry:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1712345678

Tier Access

Some skills require a minimum tier:

Calling a skill above your tier returns 403 Tier Required with upgrade info:

1
{
2
  "error": "TIER_REQUIRED",
3
  "required_tier": "professional",
4
  "current_tier": "starter",
5
  "upgrade_url": "/pricing"
6
}

Security Best Practices

• Rotate keys periodically — revoke and regenerate every 90 days
• Use scopes — if a key only needs rate-lookup, scope it to rate-lookup
• Never commit keys — use environment variables and secret managers
• Revoke immediately — if a key is exposed, revoke it from the dashboard

Receipt Verification

Every response includes receipt_id and auth_obj_id. You can verify a receipt via the audit endpoint:

$
curl https://freightrateintelligence.com/v1/reports/audit?receipt_id=rcpt_... \
>
  -H "Authorization: Bearer fri_your_key_here"

This returns the full provenance chain — which data sources, which factor versions, which timestamps produced the original answer.