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

# Authentication

> Authenticate requests with a secret key.

Send a **secret key** as a bearer token in the `Authorization` header of every request:

```bash theme={null}
curl https://api-dashboard.payra.com/v1/account \
  -H "Authorization: Bearer sk_test_..."
```

A request without a key, or with a key that does not exist or has been revoked, answers `401`. See
[Errors](/errors) for the codes.

## Key types

| Type            | Prefix                 | Where it belongs                                                                                                                                                                                                                                                                                                                                |
| --------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Secret key      | `sk_test_`, `sk_live_` | Your server only. It authenticates API requests.                                                                                                                                                                                                                                                                                                |
| Publishable key | `pk_test_`, `pk_live_` | The browser, through [Elements](/elements). It opens two endpoints with a session's `client_secret`, [retrieve](/api-reference/payment-method-sessions/retrieve-a-payment-method-session) and [confirm](/api-reference/payment-method-sessions/confirm-a-payment-method-session); server endpoints answer it `401 publishable_key_not_allowed`. |

Server endpoints answer without an `Access-Control-Allow-Origin` header, so a browser cannot call them. The two browser endpoints are the payment method
session retrieve and confirm, which is what Payra Elements calls, with the session's `client_secret` in the query
string; see [Payment method sessions](/payment-method-sessions).

## Create and store keys

Keys are created in the Payra dashboard, under **Settings → Integrations**, by a user whose role has the
**Manage API Keys and Webhooks** permission.

* The full key is shown once, at creation. Payra keeps only a hash of it and a few characters from each end, to
  tell keys apart in the list, and cannot show it again.
* Keep secret keys in a secret manager or an environment variable. Never commit them to a repository or ship them in
  a mobile or browser app.
* Each key belongs to one workspace and one environment. See [Environments](/environments).

## Rotate and revoke keys

To rotate a key, create a new one, deploy it, then revoke the old one. **Rotate key**, in the key's actions menu in
**Settings → Integrations**, does this for you: **Create new key** mints a key of the same type, with the old key's
name and scope groups filled in, and shows it once, and **Revoke old key** then revokes the old one.

Revoking a key in **Settings → Integrations** takes effect immediately: the next request with that key answers
`401 invalid_api_key`.

## Scopes

Each secret key carries scopes that limit what it can do: `payment_methods:read`, `payment_methods:write`,
`payments:read`, `payments:write`, `webhooks:read` and `webhooks:write`. In the dashboard you pick them in
groups, each granting read and write, all selected by default; the dashboard also offers a Customers group
(`customers:read`, `customers:write`), which no endpoint of this API requires. Refunds use the `payments` scopes
and events the `webhooks` scopes. A request to an endpoint that needs a scope the key does not have answers
`403 insufficient_scope`. Retrieving the account needs no scope. A publishable key carries one scope only,
`payment_methods:tokenize`, and can call only the two browser endpoints above.

A workspace on which the API has not been enabled answers every request `403 developer_integrations_disabled`;
ask Payra to enable it.