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

# Authentication

> Send your secret key in the x-api-key header on every request.

Authenticate by sending your secret key in the `x-api-key` header.

```bash cURL
curl "$PAYVE_API_URL/v1/wallets" \
  -H "x-api-key: $PAYVE_API_KEY"
```

```javascript Node
const res = await fetch(`${process.env.PAYVE_API_URL}/v1/wallets`, {
  headers: { 'x-api-key': process.env.PAYVE_API_KEY },
});
```

```python Python
import os, requests

res = requests.get(
    f"{os.environ['PAYVE_API_URL']}/v1/wallets",
    headers={"x-api-key": os.environ["PAYVE_API_KEY"]},
)
```

> [!WARNING]
>
> **Do not send your key as a Bearer token.** `Authorization: Bearer sk_live_...` is read as a
> dashboard session token, not an API key, and fails with `401 Invalid or expired token`. Use
> `x-api-key`.

## 401 responses

A `401` means Payve could not accept the credential. The body is short and has no `error.code`:

```json
{
  "message": "Invalid API key",
  "error": "Unauthorized",
  "statusCode": 401
}
```

| `message` | Cause | Fix |
| - | - | - |
| `Authentication required` | No `x-api-key` header. | Send the header. |
| `Invalid API key` | The key is wrong, revoked or past its expiry. | Create a new key. |
| `API key is not valid for the live environment` | A sandbox key sent to the live API. | Use a key from the environment you are calling. |
| `API key is not valid for the sandbox environment` | A live key sent to the sandbox API. | Use a key from the environment you are calling. |
| `Invalid or expired token` | The key was sent in `Authorization: Bearer`. | Move it to `x-api-key`. |

Do not retry a `401`. The same request will fail the same way.

## 403 responses

A `403` means the key is valid but may not do this. There are two shapes.

A key that lacks the scope for a payout gets:

```json
{
  "message": "Insufficient scope. Required: payouts:write",
  "error": "Forbidden",
  "statusCode": 403
}
```

Other permission refusals use the standard error envelope:

```json
{
  "error": {
    "code": "forbidden",
    "message": "You do not have permission: conversions:create",
    "requestId": "req_8a1c4e2f9b7d3a60"
  }
}
```

| Cause | Fix |
| - | - |
| The key lacks a scope. | Create a key with that [scope](/get-started/api-keys.md#scopes). |
| The action is dashboard-only, such as creating a webhook endpoint. | Do it in the dashboard. |
| `kyc_tier_insufficient`: your business is not verified yet. | Finish verification. See [Going live](/get-started/going-live.md). |
| `merchant_suspended`: the account is suspended. | Contact [support](/support.md). |

> [!NOTE]
>
> Handle both shapes. Read the HTTP status first, then look for `error.code`, and fall back to the
> top-level `message`.

## Never put a key in a browser or mobile app

> [!WARNING]
>
> A secret key can move money out of your wallets. Anything shipped to a browser or a phone can be
> read by whoever holds the device. Keep keys on your server.

* Call Payve from your backend. Have your web or mobile app call your backend.
* To take a payment from a customer without building a server flow, use a [payment link](/guides/payment-links.md). The hosted checkout needs no key.
* If a key has ever been in client code, treat it as leaked and [revoke it](/get-started/api-keys.md#revoke-a-key).

## Endpoints that need no key

`GET /v1/currencies` and `GET /v1/rates` are public.
