> ## Documentation Index
> Fetch the complete documentation index at: https://docs.florists.digital/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Send the bearer token you receive from a shop, understand scopes, and handle rotation.

The Partner API uses bearer tokens. Each token belongs to one shop, carries a fixed set of scopes, and has an expiry date.

## Receiving a token

The shop you integrate with gives you a bearer token created in **Settings** > **API Keys** (the shop-owner side is covered in [API keys](/settings/api-keys)). Treat it as an opaque secret. Do not parse it or infer shop, scope, or expiry information from its value.

The token is shown once to the shop owner when the key is created or rotated. If you lose it, ask the shop to rotate the key and send you the new token.

## Sending the token

Send the token in the `Authorization` header on every request:

```bash theme={null}
curl https://your-shop.example/api/partner/v1/whoami \
  -H "Authorization: Bearer YOUR_TOKEN"
```

The API is stateless. There are no cookies or sessions; the bearer token alone identifies the API key.

## Handling 401 responses

A missing, expired, revoked, or mistyped token returns `401`. Check the token you are sending. If it still fails, ask the shop to rotate the key.

Rotation revokes the old token immediately, so update every environment that uses it at the same time.

## Base URL

Each shop has its own base URL built from its domain, for example `https://your-shop.example/api/partner/v1`. Always call the shop's own domain.

## Scopes

Permissions are granted at the level of a whole feature, not individual fields. A key may carry any combination of:

| Scope                     | Grants                                                                               |
| ------------------------- | ------------------------------------------------------------------------------------ |
| `partner.orders.read`     | Read orders                                                                          |
| `partner.customers.read`  | Read customers (contact details withheld)                                            |
| `partner.customers.pii`   | Include personal contact details, stored addresses, and free-text notes and messages |
| `partner.customers.write` | Create customers                                                                     |
| `partner.products.read`   | Read products                                                                        |
| `partner.webhooks.manage` | Create and manage webhook subscriptions                                              |

Customer write access is usually granted together with `partner.customers.pii`, so your integration can confirm the customer it created.

Some fields are personal data. Without `partner.customers.pii`, personal contact details (names, contact details and stored addresses) and free-text notes and messages are returned as `null` where they appear; the request still succeeds with HTTP `200`. Operational fields needed to fulfil an order, such as the delivery address, the assigned florist and product and line item names, stay present so a logistics integration can route and reconcile without the scope. Each field in the API reference states whether the PII scope applies, so treat that as the source of truth. The scope only controls field visibility; it does not grant access to orders or customers by itself. Request it only if your integration genuinely needs personal data.

<Info>
  Shop owners create keys in **Settings** > **API Keys**. The token is shown once at creation, so copy it before leaving the screen. **Rotate** revokes the old token immediately and shows a new one; **Revoke** cuts the key's access immediately. See [API keys](/settings/api-keys) for the full shop-owner guide.
</Info>