# API-ключи

> Создавайте API-ключи Payment и Payout, разбирайтесь в правах и префиксах, безопасно меняйте секреты и разделяйте тестовый и рабочий доступ.

Paymos выдаёт два типа ключей на каждое окружение, у каждого своя фиксированная область действия. Утечка ключа Payment не даст увести средства: права проверяются централизованно на каждом запросе, поэтому ключ Payment не доберётся до эндпоинта выводов, на какой бы маршрут он ни попал.

## Типы ключей

| Тип | Префикс | Права |
|-----|---------|-------|
| **Payment** | `pk_` | Создавать инвойсы, читать статус, управлять платёжными каналами и читать их депозиты |
| **Payout** | `rk_` | Создавать выводы, отменять выводы, читать балансы |

У API-секретов префикс `sk_`. У секретов для подписи вебхуков — `whsec_`.

## Окружения

Каждый ключ привязан к одному окружению. Окружение закодировано в префиксе:

| Окружение | Модификатор | Пример |
|-----------|-------------|--------|
| **Рабочий режим** | `_live_` | `pk_live_…`, `rk_live_…` |
| **Тестовый режим** | `_test_` | `pk_test_…`, `rk_test_…` |

Полностью настроенный мерчант хранит восемь значений: четыре идентификатора ключей (`pk_live_…`, `pk_test_…`, `rk_live_…`, `rk_test_…`) и по секрету `sk_` к каждому из них. Секреты вебхуков считаются отдельно — `whsec_` выдаётся не на окружение, а на каждый адрес доставки, и адресов в окружении может быть несколько; см. [Вебхуки](/ru/docs/webhooks.md).

## Как устроены права

Права разделены централизованно, а не на уровне отдельных маршрутов: уровень доступа выводится из типа ключа на каждом запросе. Поэтому ключ **Payment** (`pk_`) видит только эндпоинты приёма денег, а ключ **Payout** (`rk_`) только эндпоинты вывода: создать вывод, отменить вывод, прочитать балансы.

Платёжные каналы относятся к приёму денег. Все восемь методов каналов и депозитов требуют ключ Payment и отвечают `403 payment_key_required` на ключ Payout — зеркально тому, как выводы отклоняют ключ Payment.

Балансы удивляют чаще всего: `GET /v1/balances` требует ключ Payout. Ключ Payment живёт на серверах магазина, попадает в каждый выкат и утекает первым — поэтому видеть, сколько у вас на балансе, ему не положено. Читайте балансы оттуда же, откуда запускаете выводы.

К ключу Payout можно добавить список разрешённых IP — в дашборде и, пока белый список адресов для вывода включён, по желанию. Если в списке есть адреса, запрос с любого другого отклоняется с `ip_not_allowed`. Если список пуст, ключ работает с любого адреса: так и нужно для serverless-функции или хостинга без постоянного исходящего IP. У ключа Payment такого списка нет вовсе.

Если владелец отключил белый список адресов через поддержку, список IP у рабочего ключа Payout становится обязательным. Без единого IP выводы с ключа отклоняются с `ip_allowlist_required`, а последний IP не удалить, пока белый список адресов снова не включат.

:::danger
Ключ Payout может вывести средства с вашего баланса в Paymos — относитесь к нему как к паролю от банка. По умолчанию нового получателя ключ не назначит: вывод уходит только на адрес из белого списка для вывода, а этот список меняется только в дашборде — и, если подключён второй фактор, со свежим подтверждением. Без белого списка ключ выводит на любой адрес, и пустить его в ход с чужого сервера мешает только список разрешённых IP. Если у ваших серверов постоянные IP, внесите их в список ключа, без лишних адресов.
:::

## Жизненный цикл

| Статус | Описание |
|--------|----------|
| **Active** | Ключ активен и принимает запросы |
| **Revoked** | Конечный статус. Ключ отключён навсегда, восстановить его нельзя |

## Рекомендации по безопасности

:::dash-list
- Никогда не передавайте API-секрет в клиентский код
- Регулярно меняйте секреты через дашборд — на время перехода предыдущий секрет ещё действует благодаря льготному периоду
- Используйте разные ключи для рабочего и тестового режима
- Ограничивайте ключи Payout по IP, если у серверов постоянные адреса, а при отключённом белом списке адресов — обязательно
- Храните API-секреты только в переменных окружения или в менеджере секретов
:::

Схему подписи HMAC-SHA256, которая использует эти ключи, смотрите в разделе [«Аутентификация»](/ru/docs/authentication.md).