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

# Проверка подлинности

> Защитите API с помощью Basic Auth, затем подключите каждую учетную запись WhatsApp по QR-коду, коду сопряжения или паролю.

GOWA имеет два вида аутентификации:

1. **Доступ к API**: кто может вызвать GOWA. Это базовая HTTP аутентификация.
2. **Соединение с WhatsApp**: привязка учетной записи WhatsApp к слоту устройства, так как вы связали бы WhatsApp Web.

## Доступ к API: основная аутентификация

Базовая аутентификация - единственный метод API. Ключи API или JWT для REST вызовов отсутствуют.

Задайте одну или несколько пар `user:password`, разделённых запятыми:

```bash theme={null}
# environment
APP_BASIC_AUTH=admin:changeme,ops:another-secret
# or flag
./whatsapp rest --basic-auth=admin:changeme,ops:another-secret
```

Каждая запись должна содержать непустое имя пользователя и пароль. По умолчанию слушатель `APP_HOST=0.0.0.0`, отказывается запускать без полных учетных данных. Для локальной разработки без аутентификации привяжите `APP_HOST=127.0.0.1`.

Если обратный прокси аутентифицирует каждого вызывающего абонента, то `APP_ALLOW_UNAUTHENTICATED=true` или `--allow-unauthenticated=true` явно разрешает слушателю без Базового Автора. Ограничивает прямой доступ к этому слушателю.

Отправлять учетные данные при каждом запросе:

```bash theme={null}
curl -u admin:changeme http://localhost:3000/app/info
# same as
curl -H "Authorization: Basic YWRtaW46Y2hhbmdlbWU=" http://localhost:3000/app/info
```

Пропущенные или неправильные учетные данные возвращают `401 Unauthorized`.

### Что не стоит за Базовой Авторизацией

| Маршрут | Почему |
| - | - |
| `GET /health` | Пробуждение жизни. Всегда в корне, игнорируя `APP_BASE_PATH`. |
| `POST /chatwoot/webhook`, `POST /chatwoot/webhook/{device_id}` | Вызывается Chatwoot. Зарегистрирован только тогда, когда `CHATWOOT_ENABLED=true` и защищен `CHATWOOT_WEBHOOK_SECRET`. Смотрите [Chatwoot](https://gowa-docs.mintlify.site/ru/integrations/chatwoot.md). |
| Обнаружение MCP OAuth и опорные точки `/oauth/*` | Только когда `MCP_OAUTH_ENABLED=true`. Смотрите [MCP сервер](https://gowa-docs.mintlify.site/ru/integrations/mcp.md). |
| `GET /statics/*` | QR-изображения, загрузки и скачанные носители. Работает перед основным автором. Любой, кто знает URL-адрес файла, может получить его. Только проверенные файлы JPEG, PNG, GIF и WebP в путях изображения отображаются внутри. Другие файлы загружаются в виде вложений с неактивным типом контента и `X-Content-Type-Options: nosniff`. Ограничить доступ к файлу при необходимости. |

Все остальное, включая панель инструментов `/`, `/mcp` и `/ws`, при настройке требует Базового Авторизации.

### Веб-сокет

Браузеры не могут установить заголовки при соединениях WebSockt, поэтому `/ws` принимает учетные данные в строке запроса:

```text theme={null}
ws://localhost:3000/ws?device_id=my-device&authorization=YWRtaW46Y2hhbmdlbWU=
```

`authorization` это `base64(user:password)`. Используйте TLS (`wss://`) и redact строку запроса в журналах прокси. WebSocket проверяет происхождение браузера на соответствие тем же доверенным источникам, которые используются при изменении состояния HTTP-запросов. Текущий хаб WebSocket транслирует события во все подключенные сокеты. Запрос `device_id` выбирает контекст устройства для подключения, но не изолирует доставку событий. Используйте идентификаторы устройства для фильтрации панели управления и предоставления API доступа только вызывающим, доверенным всем устройствам.

Смотрите [ссылка на WebSocket](https://gowa-docs.mintlify.site/ru/api-reference/websocket.md) для кодов событий, полезных загрузок и пример клиента.

### CORS

CORS разрешает любой источник по умолчанию. Ограничивает его через `APP_CORS_ALLOWED_ORIGINS=https://ui.example.com` (через запятую). Допустимые заголовки запросов являются `Origin`, `Content-Type`, `Accept`, `Authorization` и `X-Device-Id`.

CORS и браузер проверки происхождения разделены. Подстановочный код CORS не разрешает смену состояния или WebSockets. GOWA доверяет собственному хосту запроса, конкретному источнику CORS, `APP_TRUSTED_ORIGINS` и происхождению, настроенному на URL-адрес обратного вызова OAuth и Chatwoot. Для отдельной приборной панели настройте её точное происхождение:

```env theme={null}
APP_CORS_ALLOWED_ORIGINS=https://ui.example.com
APP_TRUSTED_ORIGINS=https://ui.example.com
```

Недоверенная мутация браузера возвращает `403 CROSS_SITE_REQUEST_BLOCKED`. Также она описывает маршруты GET, которые войдут в систему, выйти, переподключить или сбросить ссылку-приглашение. Клиенты, такие как curl, которые не посылают заголовки браузера в дальнейшем продолжают работать.

Происхождение `null` никогда не доверяется. Сервер `gowa-ui.html` через HTTP или HTTPS вместо открытия его в качестве URL-адреса `file://`. За обратным прокси, сохраните `Host`, настройте доверенные прокси с помощью `X-Forwarded-Host` или укажите общественное происхождение в `APP_TRUSTED_ORIGINS`.

## WhatsApp сопряжения

Каждая учётная запись WhatsApp занимает **слот устройства**. Сначала создайте слот, затем выполните сопряжение. Маршруты в `/devices/{device_id}` определяют устройство по пути. Эквивалентные маршруты `/app/*` используют заголовок `X-Device-Id`.

```bash theme={null}
curl -u admin:changeme -X POST http://localhost:3000/devices \
  -H "Content-Type: application/json" -d '{"device_id": "sales"}'
```

### QR code

```bash theme={null}
curl -u admin:changeme http://localhost:3000/devices/sales/login
```

```json theme={null}
{
  "code": "SUCCESS",
  "message": "Login success",
  "results": {
    "device_id": "sales",
    "qr_link": "http://localhost:3000/statics/qrcode/scan-qr-b0b7bb43-....png",
    "qr_duration": 30
  }
}
```

Откройте `qr_link` и отсканируйте его с телефона: **Настройки → Связанные устройства → Связать устройство**. Запросить новый код после `qr_duration` секунд. Панель инструментов `/` показывает QR непосредственно и обновляется в реальном времени через WebSocket.

### Pairing code

```bash theme={null}
curl -u admin:changeme -X POST \
  "http://localhost:3000/devices/sales/login/code?phone=628123456789"
```

Ответ содержит код `results.pair_code`, 8-символьный код. В телефоне выберите **Связать с номером телефона** и введите его. `phone` должен быть числом привязанного аккаунта, с кодом страны.

### Пароль

Если телефон запрашивает верификацию ключа при входе QR, GOWA хранит вызов WebAuthn и транслирует файл `PASSKEY_REQUEST` на WebSocket. Приборная панель управляет этим потоком. Чтобы управлять им сами:

1. `GET /app/passkey` возвращает вызов.
2. `POST /app/passkey/response` представляет утверждение WebAuthn (формат `PublicKeyCredential.toJSON()`).
3. Дождитесь `PASSKEY_CONFIRMATION`. Когда `result.skip_handoff_ux` активный QR-поток отправляет подтверждение автоматически. В противном случае сравните `result.code` с кодом на телефоне, затем вызовите `POST /app/passkey/confirm`.

Отправить `X-Device-Id` на все три звонка.

### Проверить результат

```bash theme={null}
curl -u admin:changeme http://localhost:3000/devices/sales/status
```

`results.is_connected` и `results.is_logged_in` являются `true` после привязки аккаунта. Сессии сохраняются в `storages/`, поэтому перезапуск не требует подключения снова.

## Выход и удаление

| Действие | Endpoint | Эффект |
| - | - | - |
| Выйти | `POST /devices/{device_id}/logout` или `GET /app/logout` | Отсоедините аккаунт от WhatsApp и очистите его сеанс. Слот остается, так что вы можете подключить его снова под тем же ID. |
| Переподключить | `POST /devices/{device_id}/reconnect` или `GET /app/reconnect` | Повторно открывает соединение с WhatsApp, не подключившись снова. |
| Удалить | `DELETE /devices/{device_id}` | Выход, затем удаляет ячейку вместе с сессией и данными чата. |

Учетная запись, отвязанная от телефона (привязанные устройства → Выйти) выходит таким же образом: слот остается и требует подключения снова.

## Контрольный список безопасности

* Всегда устанавливайте `APP_BASIC_AUTH` с надежными паролями на любое доступное из сети.
* Завершить TLS на обратном прокси; Базовые учетные данные Auth кодируются только в base64.
* Ограничить `APP_CORS_ALLOWED_ORIGINS` при вызове интерфейса браузера.
* Генерируйте стабильный `WHATSAPP_WEBHOOK_SECRET` с помощью `openssl rand -hex 32`. Пустые или опубликованные примеры секретов заменяются случайным ключом каждого процесса, который меняется при перезапуске.
* Считайте `storages/` чувствительным. Он содержит все привязанные ключи сессии. Новые файлы SQLite используют права владельца и созданные для них каталоги используют `0700`. Защищайте резервные копии с той же осторожностью.


## Related topics

- [Справочник по API](https://gowa-docs.mintlify.site/ru/api-reference/introduction.md)
- [Проверка здоровья](https://gowa-docs.mintlify.site/ru/api-reference/app/проверка-здоровья.md)
- [Аутентификация API](https://gowa-docs.mintlify.site/ru/api-reference/authentication.md)
- [Сессии и жизненный цикл соединений](https://gowa-docs.mintlify.site/ru/concepts/sessions.md)
- [Экспериментальные интерактивные сообщения](https://gowa-docs.mintlify.site/ru/examples/interactive-messages.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.