Skip to Content
FastracDocs

Authentication

Exchange your API key for an access token, send it on every call, and understand what the key is allowed to do.

Product
APIShipping Engine API
Section
Core concepts
Reading time
6 min read

In short

  • Use the OAuth2 client-credentials grant: your keyId is the client_id, and your secret is the client_secret.
  • Send the token as Authorization: Bearer <access_token>. Cache it and reuse it until it expires.
  • The key acts as your organisation owner, with the owner's role permissions. A missing permission returns 403.

How it works

Your serverYou
Token URLToken
Shipping Engine APIAPI
  1. Your server → Token URL: POST client_id + client_secret. grant_type=client_credentials
  2. Token URL → Your server: access_token, expires_in. Cache it until it expires
  3. Your server → Shipping Engine API: Any request. Authorization: Bearer <access_token>
  4. Shipping Engine API → Your server: Response. 401 means: get a new token
Get a token once, reuse it for every call until it expires, then get a new one.
EnvironmentToken URLclient_secret
Sandboxhttps://sandbox-auth.fastrac.cc/realms/users/protocol/openid-connect/tokensandboxSecret
Productionhttps://api.fastrac.cc/realms/users/protocol/openid-connect/tokensecret

Your client_id is your keyId in both environments. You don't request scopes: the permissions come from your organisation owner's role. See API credentials.

Get an access token

Send a form-encoded POST to the token URL:

curl -s -X POST "$FASTRAC_TOKEN_URL" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=client_credentials \
  -d client_id="$FASTRAC_CLIENT_ID" \
  -d client_secret="$FASTRAC_CLIENT_SECRET"
InboundResponse
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6...",
  "expires_in": 300,
  "token_type": "Bearer"
}

expires_in is the lifetime in seconds. Read it from the response instead of hard-coding it.

Cache and reuse the token

Requesting a token for every API call adds latency and load. Keep one token per environment, and replace it shortly before it expires:

# In shell scripts, request a token once and reuse $FASTRAC_TOKEN for the next few minutes.
export FASTRAC_TOKEN=$(curl -s -X POST "$FASTRAC_TOKEN_URL" \
  -d grant_type=client_credentials \
  -d client_id="$FASTRAC_CLIENT_ID" \
  -d client_secret="$FASTRAC_CLIENT_SECRET" | jq -r .access_token)

If you run several servers, share the token through your cache (for example Redis) so that each server doesn't request its own.

Add the token to every authenticated request:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6...

The word Bearer and one space come before the token. A few endpoints need no token: region lookups (/b2b/region/...) and package types (/b2b/order/category-item). Sending one there does no harm.

When authentication fails

StatusmessageCauseFix
401Missing authorization headerNo Authorization header.Add the header.
401Invalid authorization schemeThe header doesn't start with Bearer or has no token.Send Bearer <access_token>.
401A message about an invalid or expired tokenThe token expired, was cut off, or comes from the other environment.Get a new token from the token URL of the same environment as the API host.
401OAuth client is not registered in the app (…)The token wasn't issued for an organisation API key.Use your keyId and its secret, not a dashboard login.
401Organization owner is not configured for this client.Your organisation has no owner set up.Contact Fastrac support.
403You're not authorized to access this resource (Missing permissions: X).The owner's role lacks permission X.Ask your organisation admin to add it to the role.
—invalid_client from the token URLWrong client_id or secret, or an old secret after rotation.Check the values, and the environment.

Permissions

Your API key has no permissions of its own. Each call runs as your organisation owner, the account whose business verification created the organisation, and uses that owner's role. The default Admin role has every permission below. If an admin changes the owner's role, the key's access changes with it.

AreaEndpointsPermission
Regions, package types/b2b/region/..., GET /b2b/order/category-itemNone
BalanceGET /b2b/user-balance, GET /b2b/user-balance/logsNone (a valid token)
Couriers and rates/b2b/courier/..., /b2b/shipping-rateREAD_SHIPPING_RATES
COD rates and ordersRates or orders with codOption.isCod: trueUSE_COD as well
Create ordersPOST /b2b/ordersCREATE_ORDER
Read and track shipmentsGET /b2b/shipments, .../details, .../track/...READ_ORDER
Cancel an orderPOST /b2b/orders/{orderCode}/cancelREAD_ORDER
Cancel a shipment, simulate a statusPOST /b2b/shipments/cancel/{code}, .../simulate-statusCANCEL_ORDER
Read webhook settingsGET /b2b/webhook/infoREAD_WEBHOOKS
Change webhook settingsPOST /b2b/webhook/setWebhookMANAGE_WEBHOOKS

The full list of permission codes, and what each role has by default, is in Permissions.

Data belongs to the owner

Orders and shipments created with the key belong to the owner, and are paid from the owner's balance. In the dashboard, the owner sees them; other team members see only their own.

Rotating your key

Rotating replaces both secrets (secret and sandboxSecret) at once and keeps the keyId. The old secrets stop working for new token requests immediately; tokens already issued run until they expire. See Rotate a key.

Common mistakes

Mixing environments

A token from the sandbox token URL only works on the sandbox host, and the same for production. Keep the host, token URL and secret together in one configuration block per environment.

A token per request

Fetching a new token for every call adds latency and load. Cache it as shown above.

Calling the API from the browser

Anyone who can read your page can read the secret or token, and book shipments on your balance. Call Shipping Engine from your server only.

Was this page helpful?

On this page