# Ключи

API отдаёт данные одного стримера, того, кто выпустил ключ. Запросить чужие данные нельзя. Ключи выпускаются в кабинете, приложение создавать не нужно.

## Какой ключ нужен

Боту, серверу и скрипту подходит секретный ключ. Статическому сайту, который показывает данные посетителям, нужен публичный ключ: его можно вставить в код страницы. Он открывает только профиль, цели и статистику. Список донатов читается секретным ключом, на сервере или в боте.

## Где получить

[Открыть раздел «Разработчикам»](https://streamer.staging.donatty.com/developers)

В кабинете Донатти: меню аватара → «Разработчикам». Приложение создавать не нужно.

- **Секретный ключ** `dnt_pat_…` — для бота и сервера. «Выпустить секретный ключ»: название, права
  (`profile:read`, `donations:read`, `goals:read`, `stats:read`) и срок — 30, 90 или 365 дней. Значение
  показывается один раз — сохраните его в секретах программы. Никогда не вставляйте секретный ключ в код
  страницы сайта.
- **Публичный ключ** `dnt_pk_…` — для сайта. Открывает только профиль, цели и статистику, без срока.
  «Выпустить публичный ключ» с адресами сайтов (Origin): из браузера ключ принимается только с них, список
  меняется в окне «Настроить ключ». Ключ один; его значение можно снова скопировать в разделе. Ключ виден
  посетителям сайта: проверка Origin ограничивает браузеры, но не делает ключ секретным.

Действующих ключей у стримера — не больше 20, публичный ключ тоже считается; истёкшие не считаются.

Ключ передаётся только заголовком `Authorization: Bearer <ключ>`. Ключ в адресе запроса
(`?access_token=`) отклоняется с `400 token_in_query`; cookie не используются.

В разделе два блока:

- боту или серверу: «Секретные ключи», кнопка «Выпустить секретный ключ». В окне введите название, отметьте права и срок, затем нажмите «Выпустить ключ»;
- сайту: «Публичный ключ», кнопка «Выпустить публичный ключ». Укажите адрес сайта и нажмите «Выпустить ключ». Адреса меняются позже: «Настроить ключ», затем «Сохранить адреса».

> **Секретный ключ показывают один раз.**
> Скопируйте его сразу, в окне выпуска. Потом значение не посмотреть: потерянный ключ заменяют новым. Значение публичного ключа остаётся в разделе, его можно скопировать снова.

## Права секретного ключа

| Право | Что открывает |
|---|---|
| `profile:read` | ник, имя, аватар и ссылка на страницу доната |
| `donations:read` | все донаты с полным текстом, суммами, источниками, целями, медиа и статусом модерации |
| `goals:read` | цели сбора и собранные суммы |
| `stats:read` | топ донатеров и сумма за период |

Отметьте только то, что нужно боту. `donations:read` открывает и отклонённые модерацией донаты: фильтры ваших виджетов к API не применяются. Как безопасно выводить донаты на стрим, написано в [быстром старте для бота](https://developers.staging.donatty.com/quickstart/bot.md).

## Где хранить

Секретный ключ кладут в переменную окружения или в настройки бота, на сервер. Его нельзя вставлять в код сайта, репозиторий, чат или OBS: с ним любой прочитает ваши данные, пока ключ не истёк или не удалён.

Публичный ключ можно держать в коде сайта. Он работает только с адресов сайтов (Origin), которые вы указали в его настройках. Адрес ограничивает браузеры, но не делает ключ секретным: ключ видят посетители. Без указанных адресов ключ не работает вовсе.

## Сколько ключей

Публичный ключ один. Действующих ключей у стримера не больше 20, публичный ключ тоже считается. Истёкшие ключи в лимит не входят; в списке они остаются с пометкой «Истёк», пока вы их не удалите.

## Заменить секретный ключ

Срок секретного ключа продлить нельзя, права выпущенного ключа изменить нельзя. Порядок замены такой, чтобы бот ни на минуту не остался без доступа:

1. Выпустите новый секретный ключ с нужными правами и сроком.
2. Подключите его в боте или на сервере и проверьте запрос.
3. Удалите старый ключ.

Удаление ключа действует в течение минуты.

Если ключ попал в чужие руки (например, его опубликовали в репозитории или он был в адресе запроса), не ждите срока: выпустите новый и сразу удалите старый.