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

# Authentication

> API keys, restricted keys and scopes

Every request is sent from your server with a secret key in the `Authorization` header:

```bash theme={null}
curl https://bouclay.com/api/v1/customers \
  -H "Authorization: Bearer sk_test_…"
```

Create keys in the dashboard under **Developers → API Keys**.

## Kinds of key

| Key | Looks like | Can do |
| - | - | - |
| Secret key | `sk_test_…`, `sk_live_…` | Call every endpoint. |
| Restricted key | `rk_test_…`, `rk_live_…` | Call only the endpoints its scopes allow. |
| Publishable key | `pk_test_…`, `pk_live_…` | Nothing on the server API: it is refused. |

> [!WARNING]
>
> Secret and restricted keys can move money. Keep them on your server, in environment variables or a secrets manager. Never put them in a browser, a mobile app or a git repository.

## Restricted keys

A restricted key only reaches what you allow. Give each service the smallest set it needs: a usage collector only needs `usage:write`, a paywall only needs `entitlements:read`.

A scope is `{resource}:{access}`, such as `customers:read` or `refunds:write`. Write access includes read. `GET` requests need read access and everything else needs write. A request outside the key's scopes gets `403 permission_denied` naming the missing scope, and its `Idempotency-Key` is not used up.

| Resource | Covers | Access |
| - | - | - |
| `customers` | Customers, their addresses and payment methods | read, write |
| `entitlements` | `/customers/{id}/entitlements` | read |
| `credits` | Credit balance, credit purchases, credit grants, auto-reloads and credit holds | read, write |
| `catalog` | Products, plans and prices | read, write |
| `meters` | Meters | read, write |
| `usage` | Meter events and `/customers/{id}/usage` | read, write |
| `discounts` | Discounts | read |
| `subscriptions` | Subscriptions | read, write |
| `invoices` | Invoices | read, write |
| `credit_notes` | Credit notes (a refund to the card also needs `refunds:write`) | read, write |
| `payments` | Payments | read |
| `refunds` | Refunds and chargebacks | read, write |
| `checkout_sessions` | Checkout sessions | read, write |
| `portal_sessions` | Portal sessions | write |
| `payment_links` | Payment links | read, write |
| `events` | Events | read |
| `webhook_endpoints` | Webhook endpoints | read, write |
| `metrics` | Metrics | read |

`POST /subscriptions/{id}/items/{item}/preview` and `POST /subscriptions/{id}/plan-change/preview` only need `subscriptions:read`, since they change nothing.

## Test and live keys

A key's mode decides which gateway connection it charges through and which saved cards it can see. A test key can never charge a live card. See [Going live](https://docs.bouclay.com/get-started/go-live.md).


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