---
title: Authentication
description: Authenticate with a Customer API key in the correct account and environment.
---

Send this header with every operation:

```http
Authorization: Bearer <customer-api-key>
```

Dashboard sign-in tokens and webshop keys do not authorize the Customer API. For JSON request bodies, also send `Content-Type: application/json`.

## Environment and base URL

The API lives at `/api/v1/customer` on the website origin for your environment. This documentation uses:

<pre>
  <code>
    {new URL("/api/v1/customer", process.env.NEXT_PUBLIC_WEBSITE_BASE_URL).href}
  </code>
</pre>

Use the matching account key and website origin for another environment. Resource IDs and keys belong to that environment.

## Permissions

| Permission        | Operations                                                                       |
| ----------------- | -------------------------------------------------------------------------------- |
| `SHIPMENTS_READ`  | Find pickup locations; preview prices; list/get shipments, tracking, and labels. |
| `SHIPMENTS_WRITE` | Create/update drafts, request booking, and cancel shipments.                     |
| `ADDRESSES_READ`  | List/get senders and receivers.                                                  |
| `ADDRESSES_WRITE` | Create/update/delete senders and receivers.                                      |

`GET /services` requires any valid Customer API key. Read and write permissions are separate; write permission does not include read permission. Each endpoint states its required permission.

## Resource IDs and updates

The API uses the account associated with your key. Use resource IDs returned by the API. Unavailable IDs and list cursors return `404 NOT_FOUND`. Shipment reads also include shipments created through the dashboard.

For an address `PUT` update, send the complete address: all required fields and optional values you want to keep. This is not a partial update. Optional address fields left out are cleared; for example, leaving out `email` removes the saved email. Send `status` only when changing it; otherwise, its current value is kept.

Saved-address updates leave existing shipment snapshots unchanged. For draft updates, omitted `customerReference` and `deliveryNote` values are cleared.

## Inputs and pagination

Use service discovery for account-specific availability, supported package types, receiver contact requirements, and limits. Recognized enum values alone do not guarantee availability.

- Provide exactly one of `receiverId` or an inline `receiver`. Draft creation and updates save an inline receiver; price preview does not.
- Addresses require known uppercase two-letter country codes and international phone/mobile numbers when supplied.
- Package weight uses kg; dimensions use cm. One array item represents one physical package or pallet. Carrier shipments require packages; `OTHER` accepts an omitted or empty array and has zero price, no carrier booking, and no printable label.
- Lists return newest records first. `pageSize` defaults to 20 and accepts 1–200. Send `nextCursor` unchanged with the same filters; null marks the end.
- Shipment status filters accept repeated `status` parameters. `customerReference` matches exactly, including empty text. `createdFrom` is inclusive and `createdTo` exclusive; use RFC 3339 timestamps with seconds and a timezone.

See the [API reference](/reference) for all fields, supported values, conditional requirements, and schemas. Unknown payload fields are rejected.