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

# Authentication

> Authenticate your API requests with a YuvexPay API key.

All requests to `/v1/*` endpoints are authenticated with an **API key** sent as
a Bearer token in the `Authorization` header. There is no separate token
exchange — the key itself is the credential.

## Creating an API key

1. Log in to the [YuvexPay dashboard](https://app.yuvexpay.com).
2. Open **Settings > API Keys**.
3. Click **Create key**, choose the environment (sandbox or production) and
   pick the scopes the integration needs (see below).
4. Copy the key — it is shown only once at creation.

<Warning>
  The key secret is shown only once. Store it in a secrets manager or
  environment variable (`YUVEX_API_KEY`). If it leaks, revoke it from the
  dashboard and create a new one.
</Warning>

## Key format

A full key has the shape:

```
ypk_<env>_<kid>_<secret>
```

* `ypk` — fixed prefix.
* `<env>` — `test` for sandbox, `live` for production.
* `<kid>` — the public key id (10 characters). Safe to log; we also show it in
  the dashboard so you can identify which key was used.
* `<secret>` — the private material (32 characters). Never log this.

For example, a sandbox key looks like
`ypk_test_ab12cd34ef_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` and a production key
looks like `ypk_live_ab12cd34ef_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`.

## Using the key

Include the key as a Bearer token on every request:

```bash theme={null}
curl https://api.yuvexpay.com/v1/payments \
  -H "Authorization: Bearer ypk_test_ab12cd34ef_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

```javascript Node.js theme={null}
await fetch("https://api.yuvexpay.com/v1/payments", {
  headers: {
    "Authorization": `Bearer ${process.env.YUVEX_API_KEY}`,
  },
});
```

```python Python theme={null}
import os, requests

requests.get(
    "https://api.yuvexpay.com/v1/payments",
    headers={"Authorization": f"Bearer {os.environ['YUVEX_API_KEY']}"},
)
```

## Scopes

Each API key carries an explicit list of scopes. A request that calls an
endpoint outside the key's scopes is rejected with `403 FORBIDDEN`.

| Scope               | What it allows                       |
| ------------------- | ------------------------------------ |
| `payments:write`    | Create payments and refunds          |
| `payments:read`     | List and fetch payments              |
| `payments:refund`   | Issue refunds on an existing payment |
| `withdrawals:write` | Create withdrawals                   |
| `withdrawals:read`  | List and fetch withdrawals           |
| `customers:write`   | Create and update customers          |
| `customers:read`    | List and fetch customers             |
| `products:write`    | Create and update products           |
| `products:read`     | List and fetch products              |
| `documents:read`    | Read statements and documents        |
| `webhooks:read`     | List webhook deliveries              |
| `balance:read`      | Read the company's account balance   |

The wildcard `*` scope grants access to every endpoint and is reserved for trusted server-to-server integrations.

Choose the smallest set of scopes the integration needs. A public-website key
that only creates PIX charges only needs `payments:write`.

## Environments

The same base URL (`https://api.yuvexpay.com`) serves both environments — the
key prefix decides which bucket the request lands in:

* **`ypk_test_...`** → Sandbox. Fake money, predictable provider behaviour,
  webhooks fire, no financial impact.
* **`ypk_live_...`** → Production. Real provider, real settlement, real money.

<Tip>
  Use a `ypk_test_` key during development. Switch the environment variable to
  a `ypk_live_` key on deploy — the code path stays identical.
</Tip>

## IP allowlist and rotation

Keys support an optional IP/CIDR allowlist (set it per key in the dashboard).
When set, requests from outside the allowlist are rejected with
`403 IP_NOT_ALLOWED` even if the key is otherwise valid.

Rotate keys by creating a new one, updating the integration, then revoking the
old one. Key creation, rotation and revocation are auditable in the dashboard.

## Inspecting the current key

Call `GET /v1/auth/self` to retrieve metadata about the key being used. The
response is useful for verifying scopes, environment, IP allowlist and
expiration without storing them client-side:

```bash theme={null}
curl https://api.yuvexpay.com/v1/auth/self \
  -H "Authorization: Bearer $YUVEX_API_KEY"
```

```json theme={null}
{
  "apiKey": {
    "id": "5d0f8b6e-3a02-4f5b-9e1c-7c6a4a1b8c9d",
    "name": "Backend integration",
    "description": null,
    "environment": "PRODUCTION",
    "prefix": "ypk_live_ab12cd34ef",
    "scopes": ["payments:write", "payments:read", "withdrawals:write", "withdrawals:read"],
    "ipAllowlist": ["203.0.113.10"],
    "rateLimitPerMinute": 600,
    "expiresAt": null,
    "lastUsedAt": "2026-05-03T14:21:08.443Z",
    "createdAt": "2026-04-12T09:00:00.000Z"
  }
}
```