Authentication

API keys, Bearer auth, partner vs company keys, the FA-Fleet header, and scopes.

Every request to the FuelAtlas API is authenticated with an API key sent as a Bearer token. There are no cookies, no sessions, and no OAuth redirect dance — a single header authenticates every call.

cURL

curl https://api.fuelatlas.com/v1/me \
  -H "Authorization: Bearer fa_live_your_key_here"

Base URL

All endpoints live under /v1 on a single host:

Text

https://api.fuelatlas.com/v1

The machine-readable spec is served anonymously at https://api.fuelatlas.com/v1/openapi.json — no key required.

Getting a key

Create keys in the Developer Console. Two environments are available, distinguished by prefix:

fa_live_… — production keys. Operate on your real fleet, vehicles, and prices.
fa_test_… — sandbox keys. Operate on a simulated fleet with synthetic prices and guidance. Nothing you do with a test key touches production. See the Sandbox guide.

A key is shown once, at creation. Store it in a secret manager; if you lose it, revoke it and generate a new one. Keys are hashed at rest and can never be recovered.

Using the key

Send the key in the Authorization header on every request:

HTTP

GET /v1/me HTTP/1.1
Host: api.fuelatlas.com
Authorization: Bearer fa_live_3fA9…

A missing key returns 401 missing_api_key; a bad or revoked key returns 401 invalid_api_key / 401 key_revoked. See Errors for the full envelope.

Company keys vs partner keys

There are two kinds of key, and the difference decides how you address a fleet.

Company keys belong to a single fleet (one company). The acting fleet is implicit — every request operates on that company. This is what most direct integrations use.
Partner keys belong to an integration partner (a TMS or ELD vendor) that manages many fleets. A partner key can create fleets (POST /v1/fleets) and must name the fleet it is acting on for every fleet-scoped call.

Partner keys select the acting fleet with the FA-Fleet header:

cURL

curl https://api.fuelatlas.com/v1/vehicles \
  -H "Authorization: Bearer fa_live_partner_key" \
  -H "FA-Fleet: flt_8Qk2…"

Omit it on a fleet-scoped call with a partner key and you get 400 fleet_header_required. Pass a fleet the key isn't granted and you get 403 fleet_scope_mismatch. Fleet-management calls (POST /v1/fleets) are partner-level and take no FA-Fleet header.

Scopes

Keys carry OAuth-style scopes. A call into an endpoint whose scope the key lacks returns 403 insufficient_scope. Request only the scopes an integration needs.

Scope	Grants
`fleets:manage`	Create and manage fleets (partner keys only)
`vehicles:manage`	Create, read, update, deactivate vehicles
`locations:write`	Ingest vehicle location breadcrumbs
`fuelings:write`	Record and read fuelings
`routes:calculate`	Compute routes and fuel plans
`guidance:read`	Read autoguide sessions and recommended stops
`guidance:manage`	Set destination, acknowledge/skip stops, cancel guidance
`prices:read`	Query stations and prices
`trips:manage`	Create and manage dispatch trips
`webhooks:manage`	Register and manage webhook endpoints
`usage:read`	Read usage and savings reports

Introspect the key with `/v1/me`

GET /v1/me is your first-stop debugging endpoint. It requires only a valid key (no scope) and is exempt from quotas, so a maxed-out key can always inspect why. It returns the key's environment and scopes, the acting fleet (if any), the owning partner (for partner keys), and live month-to-date usage against your plan.

JSON

{
  "partner": { "id": "ptn_2b…", "name": "Acme TMS" },
  "fleet": { "id": "flt_8Qk2…" },
  "key": {
    "id": "key_9f…",
    "environment": "production",
    "scopes": ["locations:write", "guidance:read", "vehicles:manage"]
  },
  "plan": {
    "name": "Growth",
    "rate_limit_per_min": 600,
    "monthly_quota": { "locations": 5000000, "stations": 200000 },
    "used_this_month": { "locations": 812043, "stations": 4120 }
  }
}

For partner and fleet keys, partner and fleet are always present as explicit null when not applicable — so you can branch on a stable shape.

Push locations — start streaming vehicle positions.
Autoguide — the flagship: continuous fuel-stop recommendations.
TMS quickstart — provision a fleet end to end.

Authentication

#Base URL

#Getting a key

#Using the key

#Company keys vs partner keys

#Scopes

#Introspect the key with /v1/me