Authentication and scopes

Open in Claude Open in ChatGPT llms-full.txt

Every request needs an API key. Create keys in Settings → Developers (you need the Developers → Manage permission). Create one key per integration, so you can revoke one without breaking the others.

Sending the key

Send it as a bearer token:

GET /v1/vehicles HTTP/1.1
Host: api.get-fleet.com
Authorization: Bearer flt_live_3fQ...

curl -u flt_live_3fQ...: (HTTP Basic, key as the username) and an X-Api-Key header also work.

Scopes

A key can only do what its scopes allow. A :write scope includes the matching :read. A missing scope returns 403 insufficient_scope with the scope you need in required_scope.

You can only grant scopes whose permission your own role has, so a key never has more access than the person who created it. All keys in an organization also share a ceiling: the API integrations role in Settings → Users & Roles. An administrator can narrow that role to restrict every key at once (403 permission_denied).

Scope	Allows
`branches:read`	Read branches.
`vehicles:read`	Read vehicles.
`vehicles:write`	Create and update vehicles.
`users:read`	Read people in the organization (name, email, phone, branch).
`contacts:read`	Read contacts.
`contacts:write`	Create, update and delete contacts.
`vendors:read`	Read vendors.
`vendors:write`	Create, update and delete vendors.
`assignments:read`	Read vehicle assignments.
`assignments:write`	Create, update and delete vehicle assignments.
`meter_entries:read`	Read odometer and hour-meter readings.
`meter_entries:write`	Record and void meter readings.
`fuel_logs:read`	Read fuel logs.
`fuel_logs:write`	Create, update and delete fuel logs.
`work_orders:read`	Read work orders and their line items.
`work_orders:write`	Create and update work orders and add line items.
`issues:read`	Read issues.
`issues:write`	Create, update and delete issues.
`inspections:read`	Read inspection templates and submitted inspections.
`service_reminders:read`	Read service reminders.
`parts:read`	Read parts, part locations, stock levels and inventory movements.
`parts:write`	Create, update and delete parts.
`purchase_orders:read`	Read purchase orders and their line items.
`purchase_orders:write`	Create draft purchase orders and record their accounting status.
`telematics:read`	Read vehicle positions.
`telematics:write`	Send vehicle positions (GPS) from your telematics system.
`costs:read`	Read the cost ledger and cost summaries.
`costs:write`	Acknowledge cost entries exported to your ERP.
`expenses:read`	Read vehicle expenses and expense types.
`expenses:write`	Create, update and delete vehicle expenses and expense types.
`renewals:read`	Read vehicle renewals (insurance, licences, inspections).
`renewals:write`	Create, update and delete vehicle renewals.
`fleet_requests:read`	Read fleet requests, their lines and financial status.
`fleet_requests:write`	Raise, edit, submit, approve and progress fleet requests.
`financial_events:write`	Write ERP outcomes back to fleet requests: commitment, PO, bill, payment, rejection.
`accounting:read`	Read accounting dimensions, ERP references and accounting settings.
`accounting:write`	Manage dimensions and their values, ERP references, and period close.
`webhooks:read`	Read webhook endpoints, deliveries and events.
`webhooks:write`	Create, update and test webhook endpoints.

IP allowlists and expiry

When you create a key you can restrict it to IP addresses or CIDR ranges (for example 203.0.113.10 or 10.0.0.0/8); calls from elsewhere fail with 403 ip_not_allowed. You can also give it an expiry date, after which calls fail with 401 api_key_expired.

Rolling a key

Rolling issues a new key with the same name and access, and keeps the old one working for a grace period you choose (immediately, 1 hour, 24 hours or 7 days). Deploy the new key everywhere within the grace period. Roll keys periodically and whenever someone with access to them leaves.

Who the API acts as

Changes made through the API are attributed to the key, not to a person. The request log shows which key made each call, and where Fleet records a creator (work orders, meter entries) the API’s records are marked as created by the API. Fleet’s normal rules apply: the API cannot do anything that the organization’s permissions don’t allow.