Authentication

Every request is authenticated with an Authorization: Bearer flt_live_… header. API keys are issued from Management > Open API in the Fleeta web viewer (requires Owner/Admin permission) and are bound to the issuing company (masterEmail). One key = one company — the key itself is the tenant boundary; there is no separate organization ID parameter. See Tenant Isolation for the full isolation model.

Keys use the flt_live_<random> format (test keys use flt_test_*). The key string carries no plan name — your tier is read from your subscription on every request, so a key issued on one plan keeps working unchanged after you move to another. Each key carries scopes (such as devices:read) that limit what it can access. Requests lacking a required scope receive a 403 with an RFC 9457 problem response; requests with a missing or invalid key receive a 401.

Request example

curl "https://openapi.fleeta.io/v1/devices" \
  -H "Authorization: Bearer flt_live_..."

Authorization: Bearer is the only authentication header — requests without it are rejected at the gateway with a 401.

Trying it in the browser

The Try it panel next to each endpoint on the API Reference page sends the same header: paste a key into the panel's key field as the Bearer token, fill the parameters, and run the request without leaving the reference. No key yet? Use a public test key — flt_test_ent_0000000000000000001 returns a demo fleet and reaches no customer data. See the Sandbox guide.

Scopes by tier

The tier is derived from your Fleeta subscription plan when the key is issued — it is not chosen by you (see Rate Limits). The set of scopes that can be granted depends on that tier; the full breakdown follows.

Scope	Description	free	starter	standard	pro	enterprise
devices:read	List/detail devices, battery, firmware, settings, vehicle groups	✓	✓	✓	✓	✓
gps:read	Latest locations, trips, GPS tracks	—	✓	✓	✓	✓
events:read	Safety event list/detail, thumbnails, stats	—	✓	✓	✓	✓
usage:read	API usage, quota lookup, and API request logs	—	✓	✓	✓	✓
insights:read	Fleet summary, driving reports	—	—	✓	✓	✓
video:read	Issue event video URLs	—	—	✓	✓	✓
devices:write	Update devices, pre-register, reboot	—	—	—	✓	✓
gps:export	Create and manage GPS Export jobs	—	—	—	✓	✓
media:read	List SD-card recordings and read their metadata	—	—	—	✓	✓
media:recall	Recall a recording — uses the vehicle's mobile data	—	—	—	✓	✓
geofences:read	Geofences and alert history	—	—	—	✓	✓
geofences:write	Create/update/delete geofences	—	—	—	✓	✓
webhooks:manage	Manage webhook subscriptions	—	—	—	✓	✓
media:write	Delete recordings from the SD card (permanent)	—	—	—	—	✓
audit:read	Audit log lookup	—	—	—	—	✓

Scopes are cumulative — free: 1 scope / starter: 4 / standard: 6 / pro: 13 / enterprise: 15. We recommend granting only the minimum scopes needed. The tier is also tied to rate limits and volume quotas — see Rate Limits.

Device settings are read-only over the API: GET /v1/devices/{psn}/settings falls under devices:read, and there is no write counterpart — settings changes are made in the official webviewer/app. See Device Settings.

video:read is available from the standard tier; how much you can use it is set by the monthly transfer_bytes allowance rather than by the scope (5.6 GB of video per camera a month on standard, 10 GB on pro, 18 GB on enterprise — see Rate Limits). Exceeding it returns 403.

How scopes track plan changes (tier_default vs explicit)

How a key reacts to plan changes depends on whether you specified scopes at issuance:

• Default keys (no scopes specified at issuance) carry their tier's full scope set, resolved at request time. When the plan's scope list changes — a scope is added to or removed from your tier — default keys pick it up immediately, without reissuing the key.
• Explicit keys (a scope subset specified at issuance) are fixed to that subset, intersected with what the tier currently allows. They never silently gain scopes; to broaden one, issue a new key.

Authentication failure responses

Missing or invalid credentials return 401:

{
  "type": "https://developers.fleeta.io/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "code": "unauthorized",
  "detail": "A valid API key is required (Authorization: Bearer flt_...).",
  "requestId": "8916e1c1-2f4a-4d1e-9a7b-0b2c3d4e5f60"
}

A valid key lacking the required scope returns 403 — the requiredScope extension field tells you which scope is needed:

{
  "type": "https://developers.fleeta.io/errors/insufficient_scope",
  "title": "Forbidden",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "This operation requires the 'gps:export' scope.",
  "requestId": "1c7209ba-f033-475e-9289-e20452412b18",
  "requiredScope": "gps:export"
}

See the Errors guide for the error format in general.

Key handling rules

• The key plaintext is shown only once, right after issuance. The server stores only the sha256 hash of the key — never the plaintext — so a lost key cannot be recovered and must be reissued.
• Never hardcode keys in source code or on the client side (browser/app). Manage them via environment variables or a secrets manager, and make API calls from the server side.
• If you suspect a leak, revoke the key in the webviewer immediately and issue a new one. Revoked keys fail authentication within five minutes (our authorization cache). To see what the key did before it was revoked, filter API Logs by its keyId.
• Keys used by an MCP connector: see Rotating or revoking the key behind a connector — OAuth connectors (ChatGPT, Claude OAuth) must be re-authorized with the new key; header-mode clients only need the new value.
• Issuing separate keys per use case (e.g., a read-only dashboard vs. an Export batch) limits the blast radius of a leak.

Related links

• Tenant Isolation — the key = tenant boundary model
• Rate Limits — per-tier rps and quotas
• API Logs — which key made which call, and how it ended
• Errors — RFC 9457 problem+json
• Getting Started — from key issuance to your first call