> Расположение: Авторизация от имени сотрудника
> Краткое содержание: Как включить у бота авторизацию от имени сотрудника: где хранится секрет, адреса возврата, client_id и client_secret, запрашиваемый доступ, страница на витрине, отключение и те же настройки через API
> Это Markdown-версия конкретной страницы. Для контекста за её пределами (правила API, полный перечень методов, авторизация) ОБЯЗАТЕЛЬНО открой [llms.txt](https://dev.pachca.com/llms.txt) перед ответом — это сэкономит токены и предотвратит неполный ответ.


# Настройка авторизации

Авторизация от имени сотрудника и страница бота в витрине настраиваются на вкладке **OAuth** в карточке бота. Менять их могут создатель бота и администраторы пространства, если бот открыт им для редактирования — подробнее в разделе [Настройки бота](/guides/bots/settings#kto-mozhet-redaktirovat-nastroyki-bota).

> Одной вкладки **OAuth** для авторизации мало: сотрудник должен суметь написать боту, а бот — узнать о сообщении и ответить кнопкой. Всё, что должно быть включено у бота, собрано в [Чек-листе запуска](/guides/oauth/checklist).


## Включение

Откройте бота на вкладке **Управление** в разделе **Интеграции** > **Боты** и перейдите на вкладку **OAuth**. Пока авторизация выключена, на ней одна карточка с кнопкой **Включить**.

![Вкладка «OAuth» в карточке бота до включения авторизации: карточка с кнопкой «Включить»](/images/oauth/oauth_disabled.webp)

*Вкладка «OAuth» до включения авторизации*


Нажмите **Включить**: откроется окно **Включение авторизации** с тремя полями.

![Окно «Включение авторизации»: где хранится секрет, Redirect URI и запрашиваемый доступ](/images/oauth/oauth_enable.webp)

*Окно «Включение авторизации»*


**Где хранится секрет** — от этого зависит, как бот обменивает код авторизации на токен:

- **Серверное, с секретом** — код обменивает ваш сервер, а `client_secret` хранится только на нём. Подходит боту, у которого есть свой бэкенд.
- **Браузер, мобильное, CLI** — секрета нет, код обменивается по PKCE. Подходит приложению, которое работает на устройстве сотрудника и не может спрятать секрет.

**Адреса возврата** (поле **Redirect URI**) — куда браузер вернёт сотрудника после согласия, каждый адрес с новой строки. Правила:

- HTTPS обязателен для всех адресов, кроме адресов на этом же компьютере: `localhost`, `127.0.0.1` и `[::1]`.
- Адрес в ссылке авторизации должен совпадать с одним из списка точно. Параметры запроса при сравнении не учитываются, а у адресов на этом же компьютере — ещё и порт: приложению на компьютере сотрудника подойдёт любой свободный.
- Нужен хотя бы один адрес.

**Запрашиваемый доступ** — права, которые бот попросит у сотрудника на экране согласия. Отметьте только нужные, их можно найти поиском: без выбора авторизацию не включить. Подробнее — в разделе [Запрашиваемый доступ](#zaprashivaemyy-dostup).

Нажмите **Включить** в окне. У серверного приложения сразу откроется окно **Авторизация включена** с `client_id` и `client_secret`: секрет показывается один раз, скопируйте его кнопкой **Скопировать и закрыть**.

## Идентификатор и секрет

![Вкладка «OAuth» с включённой авторизацией: где хранится секрет, client_id, client_secret и адреса возврата](/images/oauth/oauth_tab.webp)

*Вкладка «OAuth» в карточке бота*


После включения на вкладке видны `client_id` и замаскированный `client_secret`. `client_id` не секретный: он входит в ссылку авторизации.

Если секрет утёк, нажмите значок обновления рядом с `client_secret` и подтвердите **Обновить секрет**. Старое значение перестанет работать сразу, поэтому сначала подготовьте бота к замене. Уже выданные авторизации и полученные токены продолжат работать, новое значение показывается один раз.

Настройку **Где хранится секрет** можно поменять позже. При переходе на вариант **Серверное, с секретом** `client_secret` показывается один раз, как при включении.

Адреса возврата меняются в поле **Redirect URI** на той же карточке: поправьте список и нажмите **Сохранить** под полем.

## Запрашиваемый доступ

Набор разрешений, которые бот попросит у сотрудника на экране согласия. Его же видно на странице бота в [витрине](/guides/bots/showcase) в блоке **Что бот может запросить**. Набор выбирается при включении, а потом меняется в блоке **Запрашиваемый доступ**: нажмите **Изменить**, отметьте права и сохраните.

![Блок «Запрашиваемый доступ»: список запрашиваемых разрешений и кнопка «Изменить»](/images/oauth/scopes.webp)

*Блок «Запрашиваемый доступ»*


- Набор один на бота. Параметр `scope` в ссылке авторизации ни на что не влияет: сервер всегда подставляет набор из настроек.
- В набор можно включить только права, доступные самому боту. Права, которые выдаются лишь персональным токенам, запросить нельзя.
- Права каждой авторизации дополнительно ограничены ролью сотрудника: право, недоступное его роли, работать не будет.
- Изменение набора не меняет уже выданные авторизации. Добавленные права сотрудник подтвердит при следующей авторизации, а убранные останутся в выданных токенах, пока сотрудник не отзовёт доступ или авторизацию у бота не отключат.

Выдавайте минимально необходимое: чем короче список, тем охотнее сотрудники соглашаются.

## Страница на витрине

Блок **Страница на витрине** на этой же вкладке публикует бота в [витрине](/guides/bots/showcase): в нём описание и скриншоты для страницы бота и переключатель **Опубликовать в витрине**. Как заполнить страницу и опубликовать бота — в разделе [Как опубликовать бота](/guides/bots/showcase#kak-opublikovat-bota).

## Отключение

Блок **Удаление OAuth-клиента** внизу вкладки отключает авторизацию у бота.

![Блок «Удаление OAuth-клиента» с кнопкой «Удалить OAuth-клиента»](/images/oauth/oauth_delete.webp)

*Блок «Удаление OAuth-клиента»*


После подтверждения:

- все авторизации, выданные сотрудниками, отзываются: токены сотрудников у бота перестают работать, и следующий запрос с ними вернёт `401`;
- бот пропадает из витрины, а описание и скриншоты удаляются без возможности вернуть;
- новые авторизации с этим `client_id` не проходят.

Собственные токены бота продолжают работать. Если авторизацию включить снова, у бота будут прежние `client_id` и `client_secret`, если секрет не обновляли, а в витрину бот вернётся только после новой публикации.

## Через API

Те же настройки задаются методом [Редактирование бота](/api/bots/update) или сразу при создании методом [Новый бот](/api/bots/create):

| На вкладке | В API |
| --- | --- |
| **Включить** и **Где хранится секрет** | `oauth_client.confidential`: `true` — серверное, с секретом, `false` — браузер, мобильное, CLI |
| **Адреса возврата** | `oauth_client.redirect_uris` |
| **Запрашиваемый доступ** | `oauth_client.scopes` |
| **Страница на витрине** | `promo.published`, `promo.description` и `promo.promo_images` |
| **Удаление OAuth-клиента** | `oauth_client: null` |

Объект `oauth_client` включает авторизацию, если она выключена, и меняет её настройки, если включена. Права для набора берут из [Каталога прав бота](/api/bots/list-scopes). У серверного приложения `client_secret` приходит в ответе один раз: при включении и при переходе на вариант с секретом. Новый секрет выпускает метод [Ротация секрета клиента](/api/bots/rotate-client-secret).

Включена ли авторизация, показывает поле `oauth_client_enabled` в объекте бота: параметры в `oauth_client` могут прийти и у бота с выключенной авторизацией.

Скриншоты для витрины загружают так же, как вложения сообщений, методом [Получение подписи, ключа и других параметров](/api/files/uploads), а их `key` передают в `promo.promo_images`.


## Связанные разделы

- [Чек-лист запуска](/guides/oauth/checklist)
- [Получение токена](/guides/oauth/flow)
- [Боты: Витрина](/guides/bots/showcase)
- [Боты: Общение с ботом](/guides/bots/conversations)