Public app и OAuth: как другие аккаунты подключают приложение

Обновлено: 11 ноября 2026 · 8 мин чтения

Шаги

1. 1

   Подготовка

   1. На developer.clomni.ai нажмите «New app» и выберите тип «Public app». Тип потом изменить нельзя.
   2. Укажите redirect URI (не больше 10): адрес, на который Clomni возвращает администратора после того, как он дал согласие. Адрес должен совпадать буква в букву: схема, хост, порт, путь, query. Звёздочка, # и имя пользователя недопустимы.
   3. Принимается только https. http://localhost, http://127.0.0.1, http://[::1] нужны для локальной проверки и работают с любым портом, но только пока приложение не стало Live.
   4. Отправьте scope на review (проверку). В публичном приложении каждый scope проходит review.
   5. Если у Вас есть сервер, создайте client secret. Если секрета нет, приложение считается публичным клиентом (public client) и работает только с client_id и PKCE (для браузера и мобильного приложения). После создания секрета он всегда требуется в запросе токена.
2. 2

   Отправьте администратора на адрес authorize

   Приложение создаёт code_verifier (43-128 символов), вычисляет из него code_challenge = BASE64URL(SHA256(code_verifier)), создаёт случайный state и сохраняет оба значения в сессии. Затем оно отправляет администратора на этот адрес:

   https://my.clomni.co/oauth/developer/authorize?client_id=capp_xxx&redirect_uri=https%3A%2F%2Fapp.example.com%2Fclomni%2Fcallback&response_type=code&scope=contacts:read%20conversations:read&state=STATE&code_challenge=CODE_CHALLENGE&code_challenge_method=S256

   Обязательны все параметры: client_id, redirect_uri, response_type=code, scope (scope, которые запросило приложение и которые не отклонены), state (не больше 500 символов), code_challenge (43 символа), code_challenge_method=S256. Если client_id не распознан или redirect_uri не совпадает, Clomni не перенаправляет и показывает ошибку на своей странице. Остальные ошибки возвращаются на redirect URI в виде ?error=...&state=...: invalid_request, invalid_scope, unsupported_response_type, access_denied (администратор отказал).

3. 3

   Администратор даёт согласие

   На экране согласия видны «{name} wants to connect to Clomni», «Developer: {company}», выбор «Workspace» и список «The app will be able to». Администратор нажимает «Allow» или «Deny». Подключить приложение может только администратор workspace. Запрос действует 10 минут и используется один раз. Что видно в панели: статья «Страница Apps в панели: подключение приложения, разрешения и отключение».

4. 4

   Обменяйте код на токен

   Clomni возвращает: https://app.example.com/clomni/callback?code=...&state=.... Сначала сравните state со значением в сессии. Код действует 60 секунд и только один раз. Если он придёт второй раз, токены, выданные по первому разу, тоже отзываются.

   curl -X POST https://api.clomni.ai/v1/oauth/token \
     -u "$CLOMNI_CLIENT_ID:$CLOMNI_CLIENT_SECRET" \
     -d grant_type=authorization_code \
     -d code="$CODE" \
     -d redirect_uri="https://app.example.com/clomni/callback" \
     -d code_verifier="$CODE_VERIFIER"

   Публичный клиент вместо -u передаёт client_id в теле. В ответе есть access_token (clomni_at_, 1 час), refresh_token (clomni_rt_, 90 дней), scope, workspace_id и installation_id. Храните токены по installation_id: один workspace это одна установка.

5. 5

   Обновите токен

   Отправьте запрос на тот же адрес с grant_type=refresh_token и refresh_token=.... При каждом обновлении приходит новый refresh token: удалите старый. Если старый refresh token придёт второй раз, Clomni считает это кражей и отзывает всё семейство токенов, и администратору придётся подключить приложение заново. Не обновляйте одну установку одновременно из двух процессов. Если передать scope, токен сужается, но не расширяется.

6. 6

   Работающие scope и отзыв

   В каждом запросе работают scope из пересечения: те, на которые администратор дал согласие, и те, что одобрены у приложения сейчас. Новый одобренный scope не добавляется в существующие установки сам: администратор должен подключить приложение заново. Когда администратор отключает приложение в «Settings › Workspace settings › Apps», раздел «Connected apps», все токены сразу перестают работать, а на вебхук приложения уходит app.uninstalled. Если человек, который подключил приложение, больше не администратор, токены возвращают 403 installation_owner_not_admin. Вы можете сами отозвать токен через POST /v1/oauth/revoke.

7. 7

   Проверка до review и каталог

   До review приложение можно подключить в его собственном workspace, как владелец, и проверить в тестовом канале: неодобренные scope работают только там (статья «Тестовый канал: проверка приложения без реальных клиентов»). Когда листинг одобрен, приложение появляется в каталоге в панели. Кнопка «Connect» открывает адрес установки приложения (install_url), и процесс запускает Ваше приложение.

8. 8

   Ошибки токена

   • 400 invalid_grant: код или refresh token неверный, истёк, уже использован, redirect_uri или code_verifier не совпадает, установка отозвана.
   • 401 invalid_client: client_id или client_secret неверный, или приложение с секретом его не передало.
   • 400 unauthorized_client: приложение не публичное, приостановлено или архивировано.
   • 400 invalid_scope, unsupported_grant_type.