Authentication and API keys
Create live and test API keys in the Maxmove dashboard, limit them to the permissions they need, and send them with every request.
Every request authenticates with an API key of one Maxmove workspace. Keys are created in the dashboard and come in two modes:
| Key | Mode | What it does |
|---|---|---|
mm_live_… | Live | Creates real deliveries that are dispatched to couriers and billed to your workspace. |
mm_test_… | Test | Creates simulated deliveries that are never dispatched or billed. See Test mode. |
Create a key#
Open the API keys settings
In the Maxmove dashboard, go to Settings → API keys. The section exists in the web dashboard for business and fleet workspaces. Only owners and admins can create and revoke keys.
Configure the key
Select Create API key, then set:
- Label: a name that tells you where the key is used, for example
ERP integration. - Mode: Test or Live. For a live key, confirm that it can create real, billable deliveries.
- Permissions: only the permissions your integration needs.
- Expiration: 30, 90, or 365 days, or no expiration.
- Label: a name that tells you where the key is used, for example
Copy the key
The full key is shown only once. Store it in your secret manager. If you lose it, revoke it and create a new one.
Revoking a key in the same section stops it immediately. Integrations using the key fail from then on.
Business workspaces have API access by default. Fleet workspaces need a plan that includes API access. Without it, you can't create keys, and requests with existing keys answer 403 api_access_disabled.
Send the key#
Send the key in the x-api-key header, or as a bearer token in the Authorization header. The API reference lists both as security schemes: partnerApiKey and partnerBearer.
curl https://api.maxmove.com/v1/vehicle-types \
-H "x-api-key: $MAXMOVE_KEY"curl https://api.maxmove.com/v1/vehicle-types \
-H "Authorization: Bearer $MAXMOVE_KEY"If you send both headers, Maxmove uses x-api-key.
Keep keys on your server. Never ship them in a browser or mobile app.
Permissions#
Each key carries a set of permissions. A request that needs a permission the key doesn't have answers 403 permission_denied. Listing vehicle types works with every valid key.
| Permission | Allows |
|---|---|
quotes:create | POST /v1/quotes |
deliveries:read | GET /v1/deliveries, GET /v1/deliveries/{deliveryId}, …/tracking, …/proof-of-delivery |
deliveries:write | POST /v1/deliveries, POST /v1/deliveries/{deliveryId}/cancel |
webhooks:manage | All /v1/webhooks endpoints |
fleet_orders:create | POST /v1/fleet/orders |
fleet_orders:read | GET /v1/fleet/orders/{fleetOrderId} |
The fleet_orders permissions are only offered for keys of fleet workspaces, and fleet orders only work with live keys. See Fleet order ingestion.
Live and test data are separate#
A key only sees data of its own mode. Deliveries, quotes, webhook endpoints, idempotency keys, and external_id values created with a test key are invisible to live keys, and the other way round.
Authentication errors#
| Status | Code | Meaning |
|---|---|---|
| 401 | missing_api_key | No key in x-api-key or Authorization. |
| 401 | invalid_api_key | The key is invalid, expired, or revoked. |
| 403 | permission_denied | The key lacks the permission for this request. |
| 403 | api_access_disabled | API access is not part of your workspace's plan. |
All error codes are listed in Errors.
Did this answer your question?