Give a partner API access

An API access integration gives a partner, a customer or your own software its own credentials to use the Transportial API. You decide exactly what it may do. Because each partner gets a separate integration, you can see its activity and revoke its access without affecting anyone else.

Create the access

1. Open the side menu (☰, top right), choose Integrations and click + Create integration.
2. Enter a Name that says who uses it, for example "Customer X order portal".
3. In Select integration type, choose API access integration.
4. In Select permissions, choose what the partner may do, for example read and create transport orders. Give only what is needed.
5. Click Generate to create the access key and Secret key, or enter your own.
6. Optionally, add the partner's IP Addresses. Calls from other addresses are refused.
7. Optionally, set Maximum requests per minute to protect your platform from heavy use.
8. Set Off/On to on and click Save.
9. Share the access key and secret with the partner through a secure channel.

Change or revoke access

• To change the permissions, open the integration, click the pencil (✎), change Select permissions and click Save.
• To give the partner new credentials, click Generate again and save. The old ones stop working.
• To stop access temporarily, set Off/On to off and save.
• To stop access for good, click Remove on the row in the integrations list.

Let the partner retry safely with an Idempotency-Key

When a call times out, the partner's software cannot tell whether Transportial already created the order. To avoid duplicates, it can send an Idempotency-Key header with a unique value, for example its own order number, on its create calls. If the same request arrives again with the same key, Transportial returns the first answer instead of creating the order twice. That answer carries the header Idempotency-Replayed: true.

• The same key with a different request is refused with status 422.
• A repeat while the first request is still running gets status 409; the partner retries a moment later.
• Only successful answers are remembered. If the first request failed, the same key can be used again.

This works on every create call by default. Administrators can change it for the whole platform:

1. Open the side menu (☰, top right) and choose Settings.
2. Click the Environment tab and open the Integrations section.
3. Under API: safe retries (Idempotency-Key), check that Honor the Idempotency-Key header is on.
4. Set Hours a key is remembered (24 by default). After that, a key can be used again.
5. Optionally, list the API operations that honor the header in Operations, separated by commas, for example create:*, update:trip. Leave it empty for all create operations.
6. Click Save at the bottom of the page.

Point the partner to the documentation

Developers find the API documentation in the developer portal. See Build on Transportial as a developer.