# 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](https://maxmove.com/en/developers/docs/test-mode). |

## Create a key

**1. Open the API keys settings**

In the [Maxmove dashboard](https://dashboard.maxmove.com), 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.

**2. 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.

**3. 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.

> **Note:**
> 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`.

```bash x-api-key
curl https://api.maxmove.com/v1/vehicle-types \
  -H "x-api-key: $MAXMOVE_KEY"
```

```bash Bearer token
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](https://maxmove.com/en/developers/docs/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](https://maxmove.com/en/developers/docs/concepts/errors).

---

Source: https://maxmove.com/en/developers/docs/authentication