Authentication & scopes
API tokens
Your integration authenticates with an API token sent as a bearer token:
Authorization: Bearer atk_live_9fK2…
- Make tokens in the dashboard: Settings → Developers for the company (owners and admins), or Portal → Developers for a merchant's own account (merchant admins).
- The token is shown once. Antivio stores only a hash of it; if you lose it, revoke it and make a new one.
- Tokens expire (default 365 days, at most 730) and can be revoked at any time; a revoked token stops working on its next request.
- Only send tokens from your servers. Never put them in a browser or a mobile app, a URL or a log.
- A token looks like
atk_live_<43 characters>_<6 characters>. The last part is a checksum, so a typo is refused at once, and secret scanners can recognise a leaked token.
Live and test mode
atk_live_… | atk_test_… | |
|---|---|---|
| Shipments it sees | all of its account's | sandbox shipments only |
| Shipments it creates | live (sandbox while your company is still under review) | always sandbox |
Simulator (/v1/sandbox/…) | refused | allowed |
| Webhook endpoints it sees | live and test | test only |
| Requests per minute | 1000 | 100 |
Sandbox shipments are free, never reach a driver and send no messages to recipients. See Sandbox & simulator.
Scopes
Each token has the scopes you chose; anything else is refused with 403 authz.forbidden.
| Scope | Lets the token |
|---|---|
shipments:read | list and read shipments, their history and labels, and the account's locations |
shipments:write | also create, change, confirm and cancel shipments and locations, print label batches |
rates:read | get quotes and read service levels |
webhooks:read | list webhook endpoints and their deliveries |
webhooks:write | also add, change, test and remove endpoints, rotate their secret, replay deliveries |
A token never has more power than the person who made it: you can only give scopes your role
has, and on every request the token is narrowed to what that person's current role allows
(403 authz.forbidden for the rest). If that person leaves the company or the merchant account,
or their account is disabled, the token stops working (403 auth.token_owner_inactive).
Company and merchant tokens. A merchant's token (made in the portal) only reaches that
merchant's shipments, locations and webhooks, whatever headers it sends. A company token reaches
the company's; when it creates a location or a shipment it says which customer it is for with
customer_account_id.
What a token can call
Tokens reach the public API only. Any other route answers
403 auth.api_token_not_allowed, whatever the token's scopes.
| Method | Route |
|---|---|
| GET, POST | /v1/shipments |
| GET, PATCH | /v1/shipments/{id} |
| POST | /v1/shipments/{id}/confirm, /v1/shipments/{id}/cancel |
| GET | /v1/shipments/{id}/events, /v1/shipments/{id}/label |
| POST | /v1/labels/batches |
| GET | /v1/labels/{id} |
| GET, POST | /v1/locations |
| GET, PATCH, DELETE | /v1/locations/{id} |
| GET | /v1/locations/geocode, /v1/locations/reverse-geocode |
| POST | /v1/quotes |
| GET | /v1/service-levels, /v1/service-levels/{id} |
| GET | /v1/webhook-event-types |
| GET, POST | /v1/webhook-endpoints |
| GET, PATCH, DELETE | /v1/webhook-endpoints/{id} |
| POST | /v1/webhook-endpoints/{id}/rotate-secret, /v1/webhook-endpoints/{id}/test |
| GET | /v1/webhook-endpoints/{id}/deliveries |
| POST | /v1/webhook-endpoints/{id}/deliveries/replay |
| GET | /v1/webhook-deliveries/{id} |
| POST | /v1/webhook-deliveries/{id}/replay |
| POST | /v1/sandbox/shipments/{id}/advance (test tokens) |
Managing tokens and revealing a webhook endpoint's secret are done in the dashboard by a person, never by a token.
All guides