Embed Token — это самый простой способ авторизовать встроенную интеграцию, которая открывается внутри REGOS в iframe. Пользователь уже вошел в REGOS, поэтому вашей интеграции не нужно показывать отдельную кнопку входа, открывать popup или просить пользователя повторно вводить пароль.
Если ваша страница уже открывается внутри REGOS, для первого запуска вам нужно сделать только две вещи: подключить Embed SDK на странице iframe и создать небольшой backend endpoint, который обменяет одноразовый embed_token на access_token.
Вам не нужно вручную работать с postMessage, если вы используете SDK. Вам не нужно передавать client_secret в браузер. Вам не нужно самостоятельно выпускать embed_token, если родительскую сторону выполняет REGOS.
Для разработчика встроенной интеграции процесс выглядит так:
regos-embed-sdk.v1.1.min.js.RegosEmbedSDK.init и укажите clientId, connectedIntegrationId и адрес вашего backend.embed_token от SDK и обменяйте его на access_token через /oauth/token.В большинстве случаев этого достаточно.
Откройте 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-сценария.
Сразу после подключения скрипта вызовите 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>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:
embed_token.connected_integration_id и origin ожидаемые./oauth/token.access_token.Обмен выполняется так:
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, родительская страница уже открывает ваш iframe и выдает SDK одноразовый embed_token. Разработчику интеграции обычно не нужно реализовывать эту сторону.
Ваша задача — подготовить iframe-страницу и backend endpoint. 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-статус или недоступен.