Every request carries one API key as a Bearer token. The key decides the partner account, the mode (live or test), what the request may do (scopes) and which fleets it can see. Request bodies can never change any of that.
GET /partner-api/v1/fleets HTTP/1.1
Host: fleetalyse.co.uk
Authorization: Bearer fpk_live_…Key classes
| Class | Prefix | Used on | Cannot |
|---|---|---|---|
| Management key | fpk_live_ / fpk_test_ | /partner-api/v1 | Read tracking data (positions, journeys). Change payment details. |
| Tracking-data key | ftk_live_ / ftk_test_ | /tracking-api/v1 | Activate, deactivate, bill, order or manage anything. |
Using a key on the other API answers 403 INSUFFICIENT_SCOPE with details.reason = "key_class". The response header Fleetalyse-Mode: live|test tells you which mode a request ran in.
GET /ping (on either API) shows the partner, mode, scopes and fleet access of the key you used. GET /me returns your account's entitlement (active or restricted), capabilities, limits and the plans (with your current prices when the key has rate_card.read) — call it at start-up to explain refused charge-creating requests to your staff.
Scopes
| Scope | Area | Allows | Key class |
|---|---|---|---|
customers.read | Customers & fleets | List and read the customers the key can see. | management |
customers.write | Customers & fleets | Create and update customers (never delete them). | management |
fleets.read | Customers & fleets | List and read fleets, their plan and provisioning state. | management |
fleets.write | Customers & fleets | Create fleets and change their name, reference and plan. | management |
devices.read | Devices & services | Devices, their service state and the operations that change them. | management |
devices.write | Devices & services | Register your own devices, claim supplied devices and update labels. | management |
operations.read | Devices & services | Read the status of activations, deactivations and other operations. | management |
services.activate | Devices & services | Activate, reactivate and change the plan of tracking services. Creates charges. | management |
services.deactivate | Devices & services | Deactivate tracking services (stops the usage charge when confirmed). | management |
hardware.read | Hardware | Partner prices, stock and your hardware orders. | management |
hardware.quote | Hardware | Create hardware quotes (prices, stock and delivery). | management |
hardware.purchase | Hardware | Accept quotes and place hardware orders. Creates charges. | management |
billing.read | Billing | Usage estimate, statements, invoices and credit headroom. | management |
rate_card.read | Billing | Your assigned service prices and effective dates. | management |
webhooks.manage | Integration | Register endpoints, send test events, rotate signing secrets, replay events. | management |
credentials.manage | Integration | Create, rotate and revoke keys with the same or narrower access. Only the account owner can grant it. | management |
tracking.read | Tracking data | Vehicles, latest positions and journeys (tracking-data keys). On a management key it only allows creating tracking-data keys. | management, tracking |
POST /tracking-credentials); tracking.read on a management key never lets it read tracking data itself.Fleet access
| Mode | Meaning |
|---|---|
selected | Only the fleets you tick. |
all_current | Every fleet that exists now. Fleets you create later are NOT added. |
all_current_and_future | Every fleet, including fleets created later. Account owner only. |
A key limited to fleets sees a customer only when one of its fleets is in scope, never sees devices without a fleet, and gets 404 RESOURCE_NOT_FOUND for everything else — it cannot tell "not yours" from "does not exist". A fleet created by a fleet-limited key is added to that key.
Creating keys
- In the portal: API credentials → Create API key. In live mode you confirm with your two-factor code first.
- Through the API:
POST /credentialsorPOST /tracking-credentialswith a key that hascredentials.manage. Only the account owner (in the portal) can create keys that themselves holdcredentials.manage, or keys for all current and future fleets. - A new key can never exceed the key or person that creates it: same or fewer scopes, a subset of the fleets, an expiry no later than the creator's, an IP allowlist inside the creator's. It always has the creator's mode.
- The secret is returned once. An idempotent replay of the same request returns the key with
"secret": null.
curl -X POST https://fleetalyse.co.uk/partner-api/v1/tracking-credentials \
-H "Authorization: Bearer $FLEETALYSE_ADMIN_KEY" \
-H "Idempotency-Key: feed-C1042" \
-H "Content-Type: application/json" \
-d '{"name": "Acme portal feed", "fleet_ids": ["flt_…"], "expires_at": "2027-10-01T00:00:00Z", "ip_allowlist": ["203.0.113.10"]}'Expiry and IP allowlists
expires_at is optional (ISO 8601 with an offset). ip_allowlist accepts addresses and CIDR ranges (up to 20 entries); requests from other addresses answer 401 with details.reason = "ip_not_allowed". The owner and the key's creator are emailed 7 days before a key expires.
Rotation
POST /credentials/{id}/rotate (or /tracking-credentials/{id}/rotate) returns a new key with the same or narrower access and keeps the old secret working for overlap_seconds (default 24 hours, at most 168 hours; 0 stops it at once). Deploy the new secret, then let the overlap run out.
created_resources decides what happens to the keys the old key created and the webhook endpoints it registered. "transfer" moves them to the new key (a routine rotation; any the new, possibly narrower key could not have created itself are revoked or disabled). "revoke" revokes and disables them together with the old key, which stops at once — use it when the key may have leaked, because anyone holding the secret could have created keys or endpoints of their own. Leaving it out means "revoke" when overlap_seconds is 0 and "transfer" otherwise. The response reports the counts in created_resources. In the portal, Rotate asks which you want whenever the key has created anything.
Each partner can have up to 1000 active keys per mode; creating more answers 409 CONFLICT with details.reason = "credential_limit". Revoke keys you no longer use, or contact support if you need more.
Revocation
DELETE /credentials/{id} revokes a key and every key it created, and disables webhook endpoints those keys registered; the response reports the counts. Revocation takes effect for new requests immediately and, including any cached tracking data, always within 60 seconds. Revoking a key never cancels devices, services or billing records.
When a team member loses access (role change, removal), keys rooted in that person that now exceed their access are revoked automatically.
Keep keys on your server
Never put a key in website JavaScript, a mobile app, a public repository or a downloadable configuration file. Your server calls Fleetalyse; your own front end calls your server. See the diagram in Tracking API.