OAuth 2.1
Позвольте другим приложениям авторизовать своих пользователей через аккаунт Bot-Hosting, по аналогии со входом через Discord. Основано на OAuth 2.1 и PKCE, поэтому подойдет любой стандартный клиент OAuth.
Ключ API нужен, чтобы управлять собственным аккаунтом. OAuth нужен, когда вы создаете приложение, которое действует от имени других людей: они входят и дают согласие, а не вставляют ключ. Так же подключаются ИИ-ассистенты вроде ChatGPT.
Как это работает
- 01 Создайте приложение Укажите название и redirect URI в настройках разработчика. Вы получите публичный client_id, без секрета.
- 02 Отправьте пользователей на авторизацию Перенаправьте на /oauth/authorize с PKCE. Пользователь входит и одобряет области доступа.
- 03 Обменяйте код Пользователь вернется с кодом. Отправьте его POST-запросом на эндпоинт токена, чтобы получить токен доступа.
- 04 Вызывайте API от их имени Передавайте токен как Bearer на /api/v1 и обновляйте его в фоне.
Эндпоинты
| Эндпоинты | Назначение |
|---|---|
| GET /oauth/authorize | Экран согласия пользователя, открывается в браузере. |
| POST /api/oauth/token | Обмен кода на токен или обновление токена. |
| POST /api/oauth/register | Dynamic Client Registration (RFC 7591), необязательно. |
| GET /.well-known/oauth-authorization-server | Метаданные для обнаружения. |
| GET /.well-known/oauth-protected-resource | Метаданные ресурса, используются клиентами MCP. |
Сроки жизни токенов
Код авторизации 10 мин Одноразовый, привязан к PKCE.
Токен доступа 7 дн. Bearer для вызовов /api/v1.
Refresh-токен 30 дн. Меняется при каждом использовании.
Обновление
Каждое обновление возвращает новый refresh-токен и отзывает старый: всегда перезаписывайте сохраненный. Если при обновлении вернулся invalid_grant, отправьте пользователя заново на шаг 1.
Безопасность
- Храните токены на сервере с привязкой к пользователю. Никогда не отдавайте их в браузер и не публикуйте в открытом репозитории.
- Токены отзываются сразу, как только пользователь отключает ваше приложение.
- В продакшене используйте redirect URI с https. Для локальной проверки допускается http.
- Токены OAuth никогда не дают прав администратора, какие бы области доступа ни были одобрены.