Авторизация

API Voxagent использует OAuth 2.0 (Authorization Code + PKCE) поверх Keycloak realm-а. Чтобы вызывать API от имени пользователя Voxagent из своего приложения — зарегистрируйте OAuth Application, выполните стандартный Authorization Code flow на сервере identity и используйте полученный access_token как Bearer-токен.

Быстрый токен для разовых вызовов в curl / Postman — откройте https://console.voxagent.ru/token будучи залогиненным. На странице показан текущий access-токен, регистрировать приложение не нужно.

1. Регистрация OAuth Application

Войдите в Voxagent и откройте https://console.voxagent.ru/developers → OAuth Applications → Create OAuth app:

• Name — произвольное человекочитаемое имя (например, My CRM Integration).
• Redirect URIs — точные URL, на которые ваш сервис будет получать authorization code (например, https://my-crm.example.com/oauth/callback). Минимум один; можно несколько для staging / prod.
• Type:
  • Public — для браузерных / SPA / мобильных приложений, которые не могут хранить секрет. PKCE обязателен.
  • Confidential — для server-side приложений. При создании выдаётся client_secret, который нужно безопасно хранить.

После создания UI покажет:

{
  "client_id":     "8f3a1c2e-...-...",
  "client_secret": "xPq..."
}

client_secret показывается один раз — скопируйте сразу. Если потеряли, ротируйте через настройки приложения.

OAuth-эндпоинты (auth_url, token_url и др.) одинаковы для всех приложений на платформе — см. §2 ниже.

2. Эндпоинты

Базовый URL: https://identity.voxagent.ru/realms/speaknode

3. Authorization Code flow с PKCE

Шаг 1 — сгенерировать PKCE-пару

code_verifier  = random url-safe string (43–128 chars)
code_challenge = BASE64URL(SHA256(code_verifier))

code_verifier сохраните на сервере / в памяти до шага 3.

Шаг 2 — редирект пользователя на authorize

Отправьте браузер пользователя на:

GET https://identity.voxagent.ru/realms/speaknode/protocol/openid-connect/auth
  ?client_id=<your-client-id>
  &redirect_uri=https://my-crm.example.com/oauth/callback
  &response_type=code
  &scope=openid profile email offline_access
  &code_challenge=<challenge>
  &code_challenge_method=S256
  &state=<csrf-random>

• Включите offline_access в scope, если нужен долгоживущий refresh_token (см. §5).
• Опционально: &kc_locale=ru — принудительный язык UI логина / писем.

Пользователь логинится в свой аккаунт Voxagent, Keycloak делает редирект на ваш callback:

https://my-crm.example.com/oauth/callback?code=<code>&state=<state>

Проверьте что state совпадает с отправленным значением.

Шаг 3 — обмен кода на токены

POST https://identity.voxagent.ru/realms/speaknode/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id=<your-client-id>
&client_secret=<your-client-secret>      # только для confidential
&code=<code>
&redirect_uri=https://my-crm.example.com/oauth/callback
&code_verifier=<verifier>

Ответ:

{
  "access_token":       "<jwt>",
  "expires_in":         86400,
  "refresh_token":      "<jwt>",
  "refresh_expires_in": 2592000,
  "id_token":           "<jwt>",
  "token_type":         "Bearer",
  "scope":              "openid profile email offline_access"
}

Шаг 4 — вызовы API

curl -X GET https://api.voxagent.ru/api/Users/me \
  -H "Authorization: Bearer <access_token>"

Бэкенд валидирует подпись JWT по JWKS и проверяет iss, aud, exp.

4. Обновление access-токена

access_token живёт 24 часа. До истечения (или при 401) обменяйте refresh_token:

POST https://identity.voxagent.ru/realms/speaknode/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id=<your-client-id>
&client_secret=<your-client-secret>      # только для confidential
&refresh_token=<refresh_token>

Возвращается новый access_token и новый (ротированный) refresh_token.

5. Время жизни токенов

Если вы не запросили offline_access, refresh_token будет привязан к SSO-сессии пользователя — после его выхода из Voxagent рефреш перестанет работать. Для фоновых интеграций всегда указывайте offline_access.

6. Logout

Отозвать сессию пользователя и refresh-токен:

POST https://identity.voxagent.ru/realms/speaknode/protocol/openid-connect/logout
Content-Type: application/x-www-form-urlencoded

client_id=<your-client-id>
&client_secret=<your-client-secret>      # только для confidential
&refresh_token=<refresh_token>

7. Чек-лист по безопасности

• Public клиенты обязаны использовать PKCE. Никогда не зашивайте client_secret в браузер, мобильное приложение или любой бинарник, который раздаёте пользователям.
• Confidential клиенты должны хранить секрет на сервере. При утечке ротируйте через настройки приложения.
• Всегда проверяйте state на callback для защиты от CSRF.
• Валидируйте id_token / access_token через JWKS (/protocol/openid-connect/certs) — не доверяйте телу JWT без проверки подписи.
• Ограничивайте redirect_uri точными значениями; избегайте wildcards.