Authentication

API keys, live and test keys, permissions, validity, revoking and passing the key in a call.

Last updated: Need help? Contact support

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#

PrefixKindBehaviour
rr_live_LiveReads and writes real data.
rr_test_TestReads 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)#

PermissionIn the panelGives access to
shipments:readRead shipmentsGET /v1/shipments, GET /v1/shipments/{ref}
shipments:writeRequest transportsPOST /v1/shipment-requests
invoices:readRead invoicesGET /v1/invoices
webhooks:manageManage webhooksno 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: 401 with E_AUTH. INTEGALL never says why a key is invalid.
  • A company has at most 20 active keys.

Replacing a key#

  1. Have a new key created.
  2. Put the new key in your system.
  3. Have the old key revoked.