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

# Authentication

> API keys: how to send them, what they can do, and how to rotate them.

Your server authenticates with an **API key** that belongs to one gateway. Keys start with `w3g_`. Send it as a bearer token:

```bash theme={null}
curl https://api.staging.paywire.xyz/payments/merchants/me \
  -H "Authorization: Bearer w3g_..."
```

`X-Api-Key: w3g_...` works too, if your HTTP client makes the `Authorization` header awkward.

> [!WARNING]
>
> An API key can create payment links and manage your keys and webhook secret. Keep it on your server. Never put it in a web page, a mobile app or a public repository.

## What a key can do

| Action | Endpoint |
| - | - |
| Read your gateway | `GET /payments/merchants/me` |
| Create payment links | `POST /payments/links` |
| Issue and revoke API keys | `POST /payments/merchants/me/api-keys`, `DELETE /payments/merchants/me/api-keys/{keyId}` |
| Read and rotate the webhook secret | `GET /notifications/merchants/me/webhook-secret`, `POST /notifications/merchants/me/webhook-secret/rotate` |

The payer-side endpoints (reading a link's checkout, creating an order, reading an order) need no key: anyone with the link or order id can use them, which is what lets the payer pay.

## Getting your first key

A Paywire admin creates your gateway in the dashboard; its first key is shown once. After that you can issue more keys yourself with the API.

## Rotating a key

A gateway can have up to **5 active keys**, so you can rotate without downtime:

**1. Issue a new key**

```bash theme={null}
curl -X POST https://api.staging.paywire.xyz/payments/merchants/me/api-keys \
  -H "Authorization: Bearer $OLD_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "label": "production 2026-10" }'
```

The response holds the new key in `apiKey`, shown this once, and its `keyId`.

**2. Deploy it**

Switch your servers to the new key and check they work.

**3. Revoke the old key**

```bash theme={null}
curl -X DELETE https://api.staging.paywire.xyz/payments/merchants/me/api-keys/$OLD_KEY_ID \
  -H "Authorization: Bearer $NEW_KEY"
```

The old key stops working at once; anything still using it gets `401`.

Find a key's id with `GET /payments/merchants/me`: it lists every key with its `id`, `prefix` (the first characters, to recognise it) and `revokedAt`.

## Errors

| Status | Meaning |
| - | - |
| `401` | No key, an unknown key, or a revoked key |
| `403` | The key is valid but can't do this (for example, managing dashboard users) |
| `409` `Merchant.TooManyKeys` | Already 5 active keys; revoke one first |
| `409` `Merchant.Disabled` | The gateway is disabled and can't take new payments |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.