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
keyIdis theclient_id, and your secret is theclient_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 server → Token URL: POST client_id + client_secret. grant_type=client_credentials
- Token URL → Your server: access_token, expires_in. Cache it until it expires
- Your server → Shipping Engine API: Any request. Authorization: Bearer <access_token>
- Shipping Engine API → Your server: Response. 401 means: get a new token
| Environment | Token URL | client_secret |
|---|---|---|
| Sandbox | https://sandbox-auth.fastrac.cc/realms/users/protocol/openid-connect/token | sandboxSecret |
| Production | https://api.fastrac.cc/realms/users/protocol/openid-connect/token | secret |
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"{
"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.
Send the token
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
| Status | message | Cause | Fix |
|---|---|---|---|
401 | Missing authorization header | No Authorization header. | Add the header. |
401 | Invalid authorization scheme | The header doesn't start with Bearer or has no token. | Send Bearer <access_token>. |
401 | A message about an invalid or expired token | The 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. |
401 | OAuth 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. |
401 | Organization owner is not configured for this client. | Your organisation has no owner set up. | Contact Fastrac support. |
403 | You'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 URL | Wrong 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.
| Area | Endpoints | Permission |
|---|---|---|
| Regions, package types | /b2b/region/..., GET /b2b/order/category-item | None |
| Balance | GET /b2b/user-balance, GET /b2b/user-balance/logs | None (a valid token) |
| Couriers and rates | /b2b/courier/..., /b2b/shipping-rate | READ_SHIPPING_RATES |
| COD rates and orders | Rates or orders with codOption.isCod: true | USE_COD as well |
| Create orders | POST /b2b/orders | CREATE_ORDER |
| Read and track shipments | GET /b2b/shipments, .../details, .../track/... | READ_ORDER |
| Cancel an order | POST /b2b/orders/{orderCode}/cancel | READ_ORDER |
| Cancel a shipment, simulate a status | POST /b2b/shipments/cancel/{code}, .../simulate-status | CANCEL_ORDER |
| Read webhook settings | GET /b2b/webhook/info | READ_WEBHOOKS |
| Change webhook settings | POST /b2b/webhook/setWebhook | MANAGE_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?