Authentication

The FreightLens Track & Trace API uses OAuth 2.0 client credentials. You exchange a
client ID and secret for a short-lived bearer token, then send that token on every
request. This flow is for server-to-server integrations — your backend calls FreightLens
directly; there is no user login.

1. Get your credentials

FreightLens issues you a client_id and client_secret per environment. You receive one
pair for the sandbox and a separate pair for production. Treat the secret like a password:
store it server-side, never embed it in browser or mobile code, and rotate it if exposed.

Environment	Token endpoint
Sandbox (test)	`https://api-test.freightlens.io/oauth/token`
Production	`https://api.freightlens.io/oauth/token`

2. Request an access token

Send a POST to the token endpoint with grant_type=client_credentials.

3. Read the response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "track-and-trace.read"
}

access_token — the bearer token to send on every API request.

expires_in — the token's lifetime in seconds. Cache the token and reuse it until
shortly before it expires; then request a new one.

scope — the granted scope. Track & trace read access is track-and-trace.read.

4. Call the API

Send the token in the Authorization header as a Bearer token.

Token lifecycle — best practice

Cache and reuse. Request one token and reuse it across many API calls until it is
close to expiry. Do not fetch a new token on every request.

Refresh before expiry. Request a fresh token a little before expires_in elapses
(a common approach is to refresh at ~85% of the token's lifetime) so a call never fails
on an expired token.

Handle 401. If a request returns 401 Unauthorized, request a new token once and
retry. Repeated 401s mean the credentials or scope are wrong.

Keep environments separate. Sandbox credentials work only against
api-test.freightlens.io; production credentials only against api.freightlens.io.

Errors

Status	Meaning	What to do
`400`	Malformed token request (missing/invalid parameters).	Check `grant_type`, `client_id`, `client_secret`, and content type.
`401`	Invalid credentials, or an expired/invalid access token.	Verify the credentials; request a fresh token and retry once.
`403`	Authenticated, but the token lacks the required scope.	Confirm the client is granted `track-and-trace.read`.

Error responses use the standard error shape:

{
  "code": "UNAUTHORIZED",
  "message": "The access token is expired or invalid."
}

Security notes

All requests must use HTTPS. Requests over plain HTTP are rejected.

Your tenant is bound to your credentials — you can only ever see your own organization's
shipments. There is no way to query another tenant's data.

If you believe a secret has leaked, contact FreightLens to rotate it; a rotated secret
invalidates the old one.

1. Get your credentials#

2. Request an access token#

3. Read the response#

4. Call the API#

Token lifecycle — best practice#

Errors#