Токены и аутентификация в Developer API

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

Шаги

1. 1

   Адрес и заголовки

   • Base URL (начало всех адресов): https://api.clomni.ai/v1, только HTTPS.
   • Заголовок токена: Authorization: Bearer <token>.
   • Когда отправляете тело: Content-Type: application/json, UTF-8. Ответ приходит в JSON.
   • Текст ошибок по умолчанию на азербайджанском, с Accept-Language: en на английском.

   Номер workspace в адресе не пишется: GET /v1/conversations возвращает диалоги workspace этого токена. Операция через API видна от имени владельца токена: во внутреннем приложении это владелец приложения, в публичном приложении это администратор, который подключил приложение.

2. 2

   Виды токенов

   • Личный токен (clomni_pat_): создаётся на портале, на 30, 60, 90, 180 или 365 дней (по умолчанию 90). Для скрипта, теста, небольшой внутренней задачи.
   • Токен приложения (clomni_at_): сервер сам получает его по client_id и client_secret, действует 1 час. Для постоянной серверной интеграции.
   • OAuth access token (clomni_at_, 1 час) и refresh token (clomni_rt_, 90 дней): для каждой установки публичного приложения. См. статью «Public app и OAuth: как другие аккаунты подключают приложение».
   • Client secret (clomni_secret_) и webhook secret (whsec_): создаются на портале, показываются только один раз.

   Clomni хранит токены только в виде хеша, поэтому не может показать токен второй раз. Если Вы его потеряли, создайте новый и отзовите старый.

3. 3

   Создайте личный токен

   Откройте приложение на портале и в разделе «Credentials» (учётные данные) нажмите «Create token». Выберите название (до 60 символов), scope и срок. Scope можно выбрать только из одобренных. messages:send и conversations:write можно выбрать и до review (проверки), но до одобрения они работают только в тестовом канале. В одном приложении одновременно может быть не больше 10 активных личных токенов. В публичном приложении личных токенов нет.

4. 4

   Получите токен приложения (client credentials)

   В разделе «Credentials» виден client_id (начинается с capp_). Кнопкой «Create secret» получите clomni_secret_.... Когда Вы создаёте секрет заново, старый работает ещё 7 дней. Запрос токена:

   curl -X POST https://api.clomni.ai/v1/oauth/token \
     -u "$CLOMNI_CLIENT_ID:$CLOMNI_CLIENT_SECRET" \
     -d grant_type=client_credentials \
     -d scope="conversations:read messages:read"

   В ответе есть access_token (clomni_at_...), expires_in: 3600, scope и workspace_id. Если scope не указан, выдаются все одобренные scope. Храните токен в памяти до конца срока и используйте повторно: /oauth/token ограничен 20 запросами в минуту. Refresh token нет, когда срок истёк, отправьте тот же запрос. Ошибки: invalid_client (401, неверные данные клиента), unauthorized_client (приложение приостановлено, архивировано, владелец не администратор или нет одобренных scope), invalid_scope, unsupported_grant_type.

5. 5

   Проверьте токен: GET /me

   GET /v1/me возвращает, кому принадлежит токен и какие scope работают, scope не требует:

   curl https://api.clomni.ai/v1/me \
     -H "Authorization: Bearer clomni_pat_xxx"

   В ответе есть app, workspace, user, token (kind, expires_at, scopes) и scopes. token.scopes это scope, записанные в токен, а scopes это те, что работают сейчас: scope, удалённого из приложения или не одобренного, там нет.

6. 6

   Когда токен сам перестаёт работать

   • Когда истёк срок: 401 token_expired или invalid_token.
   • Когда владелец приложения меняет пароль.
   • Когда Clomni приостанавливает приложение (403 app_suspended) или приложение архивируется.
   • Когда владелец приложения не администратор workspace: 403 app_owner_not_admin. Когда роль возвращают, токен снова работает.
   • Когда workspace приостановлен: 403 account_suspended, работает только workspace:read.

   Личный токен отзовите на портале, отзыв действует сразу. Токен приложения отзовите через POST /v1/oauth/revoke.

7. 7

   Защитите токен

   Токен и секрет хранятся только на сервере: их не должно быть в коде браузера, в мобильном приложении, в открытом репозитории и в логах. Создавайте отдельный токен для каждой среды, пишите в лог только последние 4 символа токена. Если Вы думаете, что токен утёк, сразу отзовите его или смените секрет, затем напишите на [email protected].