Кнопка входа для вашего сайта или приложения. Человек нажимает её, CloudGram спрашивает «Разрешить доступ?» — и ваш сайт узнаёт, кто вошёл. Пароль и номер телефона сайт не получает.
Выше — «Новое приложение». Получите client_id и client_secret. Секрет храните только на своём сервере.
Ссылка ведёт на окно согласия CloudGram. В state положите случайную строку и запомните её в сессии — так вы защититесь от подмены ответа.
После «Разрешить» CloudGram откроет ваш адрес возврата с ?code=…&state=… (после «Отмена» — с ?error=access_denied). Проверьте state и обменяйте код на токен — на сервере, с секретом. Код одноразовый и живёт 5 минут.
То же самое через curl:
Ответ на обмен уже содержит user. Позже профиль можно получить по токену:
Права перечисляются через пробел в параметре scope. Человек видит их списком в окне согласия.
| scope | Что даёт | Методы |
|---|---|---|
profile | Имя, имя пользователя и фото. Выдаётся всегда. | GET /api/oauth/me |
chats.read | Список чатов и сообщения в них | GET /api/threadsGET /api/threads/:id/messages |
messages.send | Отправка сообщений от имени человека | POST /api/threads/:id/messages |
Просите только то, что действительно нужно: для «Войти через CloudGram» достаточно profile. Любой другой метод с токеном приложения вернёт 403.
Если секрет хранить негде (чистый фронтенд, мобильное приложение), используйте PKCE: сгенерируйте code_verifier (43–128 символов), добавьте в ссылку code_challenge = BASE64URL(SHA-256(verifier)) и code_challenge_method=S256, а при обмене вместо client_secret передайте code_verifier. Методы /api/oauth/token и /api/oauth/me открыты для запросов из браузера с любого сайта.
Человек видит ваше приложение в CloudGram: Настройки → Устройства → Подключённые приложения и может отключить его в любой момент — токен перестанет работать. Чтобы выйти со своей стороны, вызовите POST /api/oauth/revoke с этим токеном. Удаление приложения здесь отключает его у всех.