Embed Token

Embed Token — это самый простой способ авторизовать встроенную интеграцию, которая открывается внутри REGOS в iframe. Пользователь уже вошел в REGOS, поэтому вашей интеграции не нужно показывать отдельную кнопку входа, открывать popup или просить пользователя повторно вводить пароль.

Если ваша страница уже открывается внутри REGOS, для первого запуска вам нужно сделать только две вещи: подключить Embed SDK на странице iframe и создать небольшой backend endpoint, который обменяет одноразовый embed_token на access_token.

Вам не нужно вручную работать с postMessage, если вы используете SDK. Вам не нужно передавать client_secret в браузер. Вам не нужно самостоятельно выпускать embed_token, если родительскую сторону выполняет REGOS.

Минимальный путь

Для разработчика встроенной интеграции процесс выглядит так:

  1. На странице, которая открывается в iframe, подключите regos-embed-sdk.v1.1.min.js.
  2. На этой же странице вызовите RegosEmbedSDK.init и укажите clientId, connectedIntegrationId и адрес вашего backend.
  3. На backend примите embed_token от SDK и обменяйте его на access_token через /oauth/token.
  4. После успешного обмена верните SDK простой успешный ответ и покажите пользователю интерфейс интеграции.

В большинстве случаев этого достаточно.

Шаг 1. Подключите скрипт на странице iframe

Откройте HTML-страницу, которую REGOS будет показывать в iframe, и добавьте скрипт Embed SDK:

<script src="https://auth.regos.uz/widget/regos-embed-sdk.v1.1.min.js"></script>

На этой странице не нужен regos-oauth-sdk.js. Он используется для обычной кнопки "Войти через REGOS", а не для embed-сценария.

Шаг 2. Запустите SDK

Сразу после подключения скрипта вызовите RegosEmbedSDK.init.

<script>
  RegosEmbedSDK.init({
    connectedIntegrationId: "connected_integration_id",
    clientId: "your_client_id",
    backendUrl: "https://integration.example.com/api/regos/embed/consume",
    parentOrigin: "https://regos.online",
    onSuccess: function (data) {
      console.log("Интеграция авторизована", data);
      // Здесь можно загрузить основной интерфейс интеграции.
    },
    onError: function (error) {
      console.error("Не удалось авторизовать интеграцию", error.message);
      // Здесь можно показать пользователю понятное сообщение об ошибке.
    }
  });
</script>

connectedIntegrationId — это идентификатор подключенной интеграции. clientId — идентификатор OAuth-клиента вашей интеграции. backendUrl — endpoint вашего backend, куда SDK отправит одноразовый embed_token.

SDK сам создаст nonce, сообщит родительской странице, что iframe готов, дождется embed_token и отправит его на backendUrl.

Минимальная страница iframe может выглядеть так:

<!DOCTYPE html>
<html lang="ru">
<head>
  <meta charset="utf-8">
  <title>REGOS Integration</title>
</head>
<body>
  <div id="app">Загрузка...</div>

  <script src="https://auth.regos.uz/widget/regos-embed-sdk.v1.1.min.js"></script>
  <script>
    RegosEmbedSDK.init({
      connectedIntegrationId: "connected_integration_id",
      clientId: "your_client_id",
      backendUrl: "https://integration.example.com/api/regos/embed/consume",
      parentOrigin: "https://regos.online",
      debug: false,
      onSuccess: function () {
        document.getElementById("app").textContent = "Интеграция готова";
      },
      onError: function () {
        document.getElementById("app").textContent = "Не удалось открыть интеграцию";
      }
    });
  </script>
</body>
</html>

Шаг 3. Создайте backend endpoint

SDK отправит на ваш backendUrl JSON-запрос. Вам нужно принять его на backend, взять embed_token и обменять его на access_token.

SDK отправляет такое тело:

{
  "embed_token": "opaque_embed_token",
  "connected_integration_id": "connected_integration_id",
  "nonce": "generated_nonce",
  "origin": "https://integration.example.com"
}

Минимальная логика backend:

  1. Принять embed_token.
  2. Проверить, что connected_integration_id и origin ожидаемые.
  3. Отправить запрос в REGOS /oauth/token.
  4. Получить access_token.
  5. Создать свою сессию или сохранить токен на backend.
  6. Вернуть SDK короткий успешный ответ.

Обмен выполняется так:

curl -X POST https://auth.regos.uz/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=embed_token" \
  -d "embed_token=opaque_embed_token" \
  -d "client_id=your_client_id" \
  -d "client_secret=your_client_secret"

Успешный ответ REGOS:

{
  "access_token": "eyJ...access_token",
  "token_type": "Bearer",
  "expires_in": 600,
  "scope": "allowed.scope another.scope"
}

После этого ваш backend может вернуть SDK простой ответ:

{
  "ok": true
}

Этот ответ попадет в onSuccess(data) на странице iframe.

Что важно понять

embed_token — не access token. Это одноразовый короткоживущий код для обмена. Его нельзя использовать для запросов к API и нельзя хранить.

client_secret используется только на backend интеграции. Никогда не передавайте его в HTML, JavaScript, localStorage, URL или мобильное приложение.

access_token, полученный после обмена, безопаснее держать на backend. Если frontend может обращаться к вашему backend, а backend уже обращается к нужным API, не возвращайте access_token в браузер.

Что делает REGOS

Если интеграция запускается внутри REGOS, родительская страница уже открывает ваш iframe и выдает SDK одноразовый embed_token. Разработчику интеграции обычно не нужно реализовывать эту сторону.

Ваша задача — подготовить iframe-страницу и backend endpoint. SDK берет на себя связь с родительской страницей.

Параметры SDK

Параметр Обязательный Описание
connectedIntegrationId Да Идентификатор подключенной интеграции.
clientId Да OAuth client id вашей интеграции.
backendUrl Да Backend endpoint интеграции, который принимает embed_token.
parentOrigin Нет Origin родительской страницы. По умолчанию https://regos.online.
timeout Нет Время ожидания ответа от родительской страницы в миллисекундах. По умолчанию 10000.
debug Нет Диагностические сообщения в консоли. Для production обычно false.
onSuccess Нет Вызывается после успешного ответа вашего backend.
onError Нет Вызывается при ошибке конфигурации, timeout, ошибке родительской страницы или ошибке backend.

Частые ошибки

RegosEmbedSDK: missing required config означает, что не передан connectedIntegrationId, clientId или backendUrl.

RegosEmbedSDK: parent window not available означает, что страница открыта не внутри iframe.

RegosEmbedSDK: crypto unavailable означает, что браузер не смог создать безопасный nonce.

RegosEmbedSDK: handshake timeout означает, что родительская страница не ответила за указанное время.

RegosEmbedSDK: backend request failed означает, что ваш backendUrl вернул неуспешный HTTP-статус или недоступен.