Authentication & security
Two ways to authenticate, the same API key underneath.
Bearer header
Send Authorization: Bearer flt_… on each request, exactly like the REST
API. Best for clients you configure yourself — Cursor, Claude in header mode,
Claude Code, server-side agents.
A header connection carries the key's full permissions unchanged. There is no consent screen to narrow them, so scope the key itself down when you issue it in Management › Open API.
OAuth 2.1
For clients that require it (ChatGPT) or offer it (Claude). The MCP server
doubles as the authorization server: Protected Resource Metadata (RFC 9728),
Authorization Server Metadata (RFC 8414), Dynamic Client Registration
(RFC 7591) and PKCE (S256) are all supported, so clients configure
themselves from the URL alone. A request without credentials receives 401
with a standard WWW-Authenticate: Bearer resource_metadata="…" header, which
triggers the client's discovery flow.
With OAuth your flt_ key is entered once, on the Fleeta consent screen,
and is never revealed to the AI client. The server seals the key inside
the access token itself using AES-256-GCM — a self-contained token, no token
database — and hands the client only that sealed token with a 1-hour
lifetime, renewable via refresh token. Tampered or forged tokens are
rejected.
Per-scope consent
The consent screen lists the key's scopes as checkboxes:
- read scopes are checked by default;
- the four write scopes —
devices:write,geofences:write,media:recall,media:write— are unchecked by default.
Only the subset you approve is sealed into the token. The MCP layer enforces
that subset (tools for non-granted scopes are blocked, and confirm_action
re-checks it at execution time), and refreshing the token can never escalate
beyond the originally granted scopes.
Token lifetimes
| Token | Lifetime |
|---|---|
| Authorization code | 10 minutes |
| Access token | 1 hour |
| Refresh token | 30 days, renewed on every refresh while in use |
Write confirmation token (mcp_cf_…) | 5 minutes |
What an agent can reach
Everything downstream is unchanged from the REST API:
- the same scopes by tier;
- the same per-key tenant isolation — an agent can only see the fleet its key belongs to;
- the same rate limits and quotas;
- the same audit logging.
Combined with the approval gate on write tools, the worst an over-eager agent can do on its own is read data its key was already allowed to read — mutations always require your explicit confirmation.
Rotating or revoking the key behind a connector
The MCP server keeps no state about your key — every tool call is authorized by the API key itself, so revoking or replacing the key in Management › Open API is the only rotation step on our side. What changes for a connected agent depends on how it authenticates.
What a revoked key does. Requests carrying a revoked key are rejected at
the gateway with 401 within at most five minutes (our authorization cache).
From then on every tool call from an agent still using that key fails with an
authentication error.
Bearer-header connections (Cursor, Claude header mode, Claude Code, local
stdio). The client sends the key on each request. Replace the value in the
client configuration (the Authorization header, or FLEETA_API_KEY for
stdio) with the new key and reload the server — nothing else is needed.
OAuth connections (ChatGPT, Claude OAuth). The access token (1 hour) and
refresh token (30 days) are sealed copies of the key you pasted on the consent
screen. They cannot be edited and there is no token-revocation endpoint — but
they are useless without the key: once the key is revoked, calls made with
those tokens fail with 401, and refreshing the token does not pick up a new
key (it re-seals the old one). To move an OAuth connector to a new key,
disconnect (or reconnect) the connector in the client and run the consent flow
again, pasting the new key and re-selecting the scopes to grant. Until you do,
the connector still looks connected but every tool returns an authentication
error.
Pending write approvals. Confirmation tokens (mcp_cf_…) are bound to the
key that issued them. A proposal made under the old key is rejected by
confirm_action after rotation — call the write tool again and approve it
afresh.
Recommended order.
- Issue the new key in Management › Open API.
- Update header-mode clients and re-authorize OAuth connectors with the new key.
- Revoke the old key.
This avoids a window with no working key; the old key keeps working for up to five minutes after revocation.
Safe-use practices
- Prefer OAuth where the client offers it — the key never leaves the consent screen.
- Least privilege — grant read scopes only unless the agent's job needs a write, and issue a dedicated key per agent so one can be revoked without touching the others.
- Prompt injection — an agent reads whatever text it is given, including text that tries to instruct it. The approval gate is what protects your vehicles from a hijacked prompt: read the summary card before you approve, every time.
- Shared assistants — a connector in a shared ChatGPT or Claude workspace is available to everyone in that workspace with the key's permissions. Connect production keys only to agents and workspaces you trust.
- Audit —
audit_logs(enterprise) and the API request log in Management › Open API show every call an agent made, with the key that made it.