Authentication

Every request to the FleetSync API is made on behalf of a service user. A service user belongs to your FleetSync account and has a client ID and a client secret. You exchange these credentials for a short-lived access token, and send the token with each GraphQL request.

Create a service user

1. Sign in to FleetSync with a user that can manage users.
2. Open Users and click Service user.
3. Enter a name that identifies the integration, for example the name of your system.
4. Copy the client ID and the client secret.

The client secret is shown only once. Store it in a secrets manager. Do not put it in source code or in a shared document.

If a secret is lost or exposed, open the service user on the Users page, choose View service account credentials, and click Regenerate secret. The previous secret and every access token issued with it stop working immediately.

Get an access token

FleetSync implements the OAuth 2.0 client credentials grant. Send the credentials as a form-encoded POST to the token endpoint:

curl -X POST https://fleetsync.io/api/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET

A successful response returns the token and its lifetime in seconds:

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 86400
}

Tokens are valid for 24 hours. Cache the token and reuse it until shortly before it expires. Do not request a new token for every API call.

If the request fails, the response has an OAuth 2.0 error body:

Call the API

Send the token in the Authorization header of every GraphQL request:

curl https://fleetsync.io/api/graphql \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "query": "{ getCars { items { id vin make model year } cursor } }" }'

GraphQL responses use HTTP status 200 even when a request is rejected. Check the errors field:

HTTP basic authentication

For tools that cannot perform the token exchange, a service user can be allowed to authenticate with HTTP basic authentication. Open View service account credentials for the service user and enable Allow HTTP basic auth. The GraphQL endpoint then also accepts the client ID and secret directly:

curl https://fleetsync.io/api/graphql \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "query": "{ getCars { items { id vin } cursor } }" }'

Prefer access tokens whenever you can. Basic authentication sends the long-lived secret with every request, while a token expires after 24 hours.

Recommendations

• Create one service user per integration. A leaked secret can then be rotated without affecting other systems.
• Treat access tokens like passwords. Anyone who holds a token can act as the service user until it expires.
• Request a token, cache it, and refresh it only when it is about to expire or after an Unauthorized error.