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

# Authentication

> Authenticate v3 requests with your Suby.fi API key.

All requests to the Suby.fi v3 API are authenticated with a secret API key sent in the `X-Suby-Api-Key` header.

```bash theme={null}
curl https://api.beta.suby.fi/v3/payments \
  -H "X-Suby-Api-Key: sk_live_your_key_here"
```

### API keys

Generate keys from your [dashboard settings](https://dashboard.beta.suby.fi/dashboard/settings). Each key is shown **once** at creation — store it securely (a secret manager, never in client-side code or a public repo).

| Prefix         | Environment    | Behaviour                                                        |
| -------------- | -------------- | ---------------------------------------------------------------- |
| `sk_live_…`    | **Production** | Real card + crypto processing, real funds.                       |
| `sk_sandbox_…` | **Sandbox**    | Fully simulated. Test cards, Base Sepolia crypto, no real money. |

The environment is **inferred from the key prefix** — you do not send a separate environment header. LIVE and sandbox data are isolated; a sandbox key never sees LIVE resources and vice-versa.

### Sandbox mode

Use a `sk_sandbox_…` key to build and test end-to-end without moving money:

* **Card payments** use test card numbers (e.g. `4242 4242 4242 4242`).
* **Crypto payments** are limited to **Base Sepolia** (chain ID `84532`). If you don't specify chains/assets, Base Sepolia and its active assets are auto-selected.
* **Refunds** on sandbox card payments skip the provider and mark the payment `REFUNDED` directly.
* **Webhooks** fire normally, so you can exercise your handlers.

### Errors

Authentication failures return `401` with the standard error envelope:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}
```

<Warning>
  Treat your `sk_live_…` key like a password. If it leaks, revoke and rotate it
  immediately from the dashboard. Suby will never ask you for your secret key.
</Warning>

### Rate limiting

Requests are rate-limited per API key. If you exceed the limit you receive `429 Too Many Requests`; back off and retry with exponential delay.