Authentication
API keys, live and test keys, permissions, validity, revoking and passing the key in a call.
The INTEGALL API only works with API keys. There are no user sessions and no cookies.
Getting a key#
The owner or an administrator of the transport company creates a key in the company panel, under SettingsIntegrations › API and webhooks. Creating one asks for a fresh code from their authenticator app. See API keys and webhooks.
The key is shown only once. After that INTEGALL only stores a hash; nobody can read the key later.
Kinds of keys#
| Prefix | Kind | Behaviour |
|---|---|---|
rr_live_ | Live | Reads and writes real data. |
rr_test_ | Test | Reads your real data, but a write call is only validated and not stored. Responses contain "sandbox": true and the header x-integall-sandbox: true. |
A key has the form rr_live_xxxxxxxx_ followed by 32 characters. The first 16 characters (the prefix) are also shown in the panel; they let you recognise a key.
Permissions (scopes)#
| Permission | In the panel | Gives access to |
|---|---|---|
shipments:read | Read shipments | GET /v1/shipments, GET /v1/shipments/{ref} |
shipments:write | Request transports | POST /v1/shipment-requests |
invoices:read | Read invoices | GET /v1/invoices |
webhooks:manage | Manage webhooks | no path in v1 |
A call without the right permission gets 403 with the code E_SCOPE.
Passing the key#
Preferably use the Authorization header:
curl -H "Authorization: Bearer $INTEGALL_API_KEY" \
"https://api.integall.com/functions/v1/api-v1/v1/invoices"The X-API-Key header also works:
curl -H "X-API-Key: $INTEGALL_API_KEY" \
"https://api.integall.com/functions/v1/api-v1/v1/invoices"Validity and revoking#
- A key is valid until it is revoked, or for 30, 90 or 365 days (chosen when creating it).
- Revoking works immediately, even between two calls: INTEGALL checks the key again on every call.
- An unknown, revoked or expired key always gets the same response:
401withE_AUTH. INTEGALL never says why a key is invalid. - A company has at most 20 active keys.
Replacing a key#
- Have a new key created.
- Put the new key in your system.
- Have the old key revoked.