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

# Get your API keys

> Create, scope, rotate and revoke the secret keys that authenticate your server.

You create API keys in the dashboard. Each key belongs to one environment and carries the scopes you give it.

> [!WARNING]
>
> **Your key is shown once.** Payve displays the full key only in the response to its creation, then
> keeps a hash. Nobody at Payve can read it back to you. If you close the dialog without copying it,
> revoke that key and create another.

## Create a key

**1. Pick the environment**

Sign in to the [dashboard](https://app.payvehq.com). Use the environment toggle to choose
**Sandbox** or **Live**. A key works only in the environment it was created in.

**2. Open API keys**

Go to **Settings → API keys** and select **Create API key**.

**3. Name it and choose scopes**

Give the key a name you will recognise later, such as `Production server`. Tick at least one
scope. Optionally set how long the key stays valid: no expiry, 30 minutes, 1 hour, 6 hours or 24
hours.

**4. Copy the key**

The dashboard shows the key under **Save your key now**. Copy it into your secret manager before
you close the dialog.

To create a key you need a verified email address and a dashboard role that can manage developer settings.

## Test keys and live keys

| Prefix | Environment | Money |
| - | - | - |
| `sk_test_` | Sandbox | Simulated. None real |
| `sk_live_` | Live | Real |

A key sent to the wrong environment is refused with `401` and the message `API key is not valid for the live environment` (or `sandbox`).

After creation, the dashboard lists each key by its prefix and last four characters only.

## Scopes

A scope limits what a key can do. You can only grant a scope for something your own dashboard role is allowed to do.

| Scope | Lets the key |
| - | - |
| `payouts:write` | Create, bulk-create, retry and cancel payouts. Create and process refunds. |
| `payouts:read` | Carries the payout view permission. |
| `payins:write` | Create, update and delete payment links. |
| `payins:read` | Carries the pay-in view permission. |
| `conversions:write` | Create conversions and resend their webhooks. |
| `conversions:read` | Carries the conversion view permission. |
| `beneficiaries:write` | Create and archive beneficiaries. |
| `beneficiaries:read` | Carries the beneficiary view permission. |
| `webhooks:read` | Grants nothing extra. Any key can list your webhook endpoints and delivery history. |

A key without the scope an endpoint needs gets `403`. [Authentication](/get-started/authentication.md#403-responses) shows the response.

> [!TIP]
>
> Give each service its own key with the fewest scopes it needs. A service that only reads payouts
> should not hold `payouts:write`.

> [!NOTE]
>
> An API key cannot create, change or delete webhook endpoints, rotate a signing secret, or request
> a statement. Do those in the dashboard.

## Rotate a key

There is no rotate button for API keys. Rotate by replacing:

**1. Create the new key**

Create a second key with the same scopes. Copy it.

**2. Deploy it**

Update your secret manager and release. Confirm your service is sending the new key.

**3. Revoke the old key**

Revoke the old key in the dashboard. It stops working at once.

Both keys work during the overlap, so you rotate with no downtime.

## Revoke a key

Open **Settings → API keys**, find the key and select **Revoke**. Revocation is immediate and cannot be undone. Every request with that key then returns `401 Invalid API key`.

> [!WARNING]
>
> Revoke a key the moment you think it has leaked: a commit, a log line, a screenshot, a laptop you
> no longer control. Then check your recent payouts.

## Keep keys safe

* Store keys in a secret manager or environment variables. Never in source control.
* Call the API from your server only. [Never from a browser or a mobile app](/get-started/authentication.md#never-put-a-key-in-a-browser-or-mobile-app).
* Do not log request headers.
* Use short-lived keys for one-off scripts.
