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

# Authenticate backend requests

> Use keys scoped by merchant and environment without exposing credentials to public clients.

The merchant API uses a Bearer key. The gateway derives the merchant, environment, actor, and scopes from that credential.

## Send the key

Include the key in the `Authorization` header:

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
Authorization: Bearer your_simplepay_api_key_here
```

Store it in a secret manager. Never place it in URLs, metadata, logs, screenshots, or client code.

## Limit scopes

Create one key per service and assign only the required scopes:

| Task                     | Primary scopes                                  |
| ------------------------ | ----------------------------------------------- |
| Create and read Checkout | `hosted_checkout:write`, `hosted_checkout:read` |
| Create and read links    | `payment_links:write`, `payment_links:read`     |
| Read payments            | `reporting:read`                                |
| Manage catalog           | `digital_catalog:write`, `digital_catalog:read` |
| Manage webhooks          | `webhooks:write`, `webhooks:read`               |

## Manage keys with a session

An API key cannot create, rotate, or revoke keys. These actions require a Customer session, an administrator role, and recent step-up.

<Danger>
  SimplePay returns a new key's full value once. It stores an obfuscated
  reference, not a recoverable secret.
</Danger>