Getting access

Access and plans

The Integration API is open on every plan, Exchange included: there is nothing to switch on. Your company’s Owner or an Admin creates integrations in the app, without waiting for Quatlas.

What the plan sets is capacity. These are the defaults:

	Exchange	Enterprise
Live integrations	1	5
Test integrations (sandbox)	1	5
Calls a minute per key	60	300
Document uploads a day per company	50 files, 250 MB	200 files, 1 GiB

Live and test integrations are counted apart, so the sandbox stays available while your live integration is in use. Every scope, the webhooks and the sandbox come with both plans, and so do the security features: OAuth, the IP allowlist, expiry and rotation, two-step verification, the call log and the audit trail. For more capacity, write to [email protected].

If your company moves from Enterprise to Exchange, nothing is revoked: every integration keeps working, at the Exchange rate, and its keys can still be rotated. A new live integration can be created once the company is under the Exchange cap again.

The Quatlas team can switch the API off for a company; its keys are then refused at once.

Creating an integration

An integration is one connection to one of your systems, with its own keys.

1. Sign in with two-step verification. Creating an integration, and rotating or revoking a key, asks for it.

2. Open Settings > Integrations and choose New integration.

3. Fill in the form:

   • Name: what the system is, for example “eBA”. Calls act as the integration’s own service identity, “Integration: eBA”, never as a person.
   • Live or test: a test integration works only in your sandbox. Start with a test one.
   • Scopes: what the key may do (see below). Grant only what the system needs.
   • Expiry: at most 12 months, 12 months by default.
   • IP allowlist (optional): the addresses or CIDR blocks the key may be used from, at most 20 entries, IPv4 and IPv6. Empty means any source.
   • OAuth only (optional): the key then works only at the token endpoint, and every call carries a 15-minute token. See Authentication.

4. Copy the key from Copy the key now. It is shown this once and is never stored: Quatlas keeps only a keyed hash of it. Put it in a secret store straight away (for example Azure Key Vault, HashiCorp Vault, or your BPM tool’s encrypted parameters).

Caution

Never send a key by e-mail or chat, and never commit it to a code repository. If a key may have leaked, revoke it in Settings > Integrations: it stops at once, and so do its access tokens.

A company holds as many live and test integrations as its plan allows (see above), and each integration at most 2 active keys (a rotation’s old and new key). The other Owners and Admins of your company are told when an integration is created.

Scopes

Scope	Allows
requests:write	Creating shipment requests, as drafts or published; updating and cancelling the requests created through the API where the app lets an owner, and keeping your metadata on them. A request opened in the app is read, never written. Moving a sandbox request (test keys).
requests:read	Reading a request’s status, offer count and deal, by id or by externalReference.
deals:read	Reading the deals your company is a party to: price, Incoterm, counterparty and stage.
tracking:read	Reading a deal’s milestones, planned and current delivery estimate, and delivery. No live position.
documents:read	Listing a deal’s documents, and a 5-minute download link for a document that passed its malware scan.
documents:write	Uploading documents to the deals your company is a party to, under the app’s upload rules.
costs:read	Reading a deal’s additional costs (approved or declared) and the statement totals, which count agreed costs only (declared ones not yet agreed are in declaredTotal).

A call to a route outside the key’s scopes answers 403 with Integration.Forbidden. The Owner or an Admin can change a key’s scopes later, with two-step verification; the change is recorded in the audit trail with its reason.

What your Owner and Admins see

Under Settings > Integrations your company’s Owner and Admins see each integration and its keys (the prefix, the scopes, the identity, the expiry, the last use and the status), and:

• the call log: the time, key, route, answer, duration and a hash of the idempotency key of every call, kept for 365 days and exportable as CSV. What your system sent is never logged.
• the audit trail: every change to a key, with who made it, when and why.
• the webhooks: subscriptions, their delivery log, redelivery and test events. See Webhooks.

The key’s prefix

A live key is qk_ followed by 43 characters, a test key qk_test_ followed by 43 characters. The first 12 characters after the marker, with the marker, are the key’s prefix: the app shows it so people can tell keys apart, and it is the OAuth client_id. The prefix is not secret; the rest of the key is.