code, а затем обменивает его на OAuth access token.
OAuth access token используется для доступа к интерфейсам ресурсов аккаунта; для вызова API моделей используется соответствующий API Key. OAuth-авторизация не создаёт автоматически API Key, не подключает сервисы и не увеличивает баланс.
Выберите способ интеграции
Стандартный переход не требует
embed=studio, embed_origin или postMessage. В режиме компонента Studio хост создаёт страницу авторизации и поддерживает мост сообщений; третьи стороны интегрируются согласно протоколу компонента в конце этой статьи, не формируйте эти два параметра самостоятельно.
Эндпоинты и документ обнаружения
Интерфейс управления приложениями требует аутентификации в аккаунте и не является интерфейсом анонимной динамической регистрации (DCR). Собственные адреса обнаружения/регистрации MCP-сервиса и OAuth-эндпоинты аккаунта из этой таблицы являются разными точками входа; при подключении к конкретному MCP действуйте согласно документации и результатам обнаружения этого сервиса.
Документ обнаружения используется для получения эндпоинтов и возможностей протокола. Текущий процесс возвращает OAuth token, но не возвращает
id_token; не обрабатывайте его как полноценный процесс входа OpenID Connect только из-за наличия scope openid.
Области разрешений: используйте текущие названия scope
scope — это разделённые пробелами, чувствительные к регистру названия разрешений. Новые приложения используют конкретные разрешения, такие как profile:read, email:read, phone:read.
Где получить доступные для запроса разрешения
После входа интерфейс списка OAuth-приложенийGET /api/v1/oauth2/applications/ возвращает available_scopes; селектор разрешений на странице управления приложением использует тот же каталог. Это доступные области, которые должны использовать обычные самостоятельно обслуживаемые приложения.
scopes_supported в Discovery содержит все распознаваемые платформой названия разрешений, но не означает, что ваше приложение может запросить каждое из них. При фактической авторизации одновременно проверяется:
- разрешено ли делегировать это разрешение данному типу приложения;
- зарегистрировано ли это разрешение в допустимых scope данного OAuth-приложения;
- имеет ли текущий пользователь запрошенное разрешение.
invalid_scope. При обмене кода авторизации и обновлении также выполняется повторная проверка; разрешения не дополняются и не повышаются автоматически.
Разрешения, доступные обычным самостоятельно обслуживаемым приложениям
Ниже приведён текущий каталог (2026-10-09); при интеграции ориентируйтесь наavailable_scopes.
Например, для чтения только личного профиля используйте
profile:read; если также нужен адрес электронной почты, добавьте email:read; для чтения существующих API Key используйте profile:read credentials:read. Запрашивайте credentials:write только если действительно требуется создавать или изменять Key, а offline_access добавляйте только когда требуется обновление.
Некоторые разрешения доступны только доверенным приложениям, одобренным платформой, например sites:read, sites:write, platform-tokens:read; другие разрешения не открыты для обычных сторонних OAuth-приложений. Типы клиента public/confidential описывают возможность хранения secret и не связаны с тем, является ли приложение доверенным. Самостоятельно созданные приложения не могут самостоятельно включать доверенные разрешения.
account — это селектор разрешений аккаунта, используемый указанным официальным MCP для управления аккаунтом, а не scope «всех разрешений» для сторонних приложений; его нельзя смешивать с другими scope. Сторонние приложения должны явно перечислять конкретные необходимые разрешения.
Миграция со старой документации
Старые названия не принимаются в качестве совместимых псевдонимов. Одновременно обновите scopes, зарегистрированные для OAuth-приложения, URL авторизации и собственную проверку разрешений; изменение конфигурации приложения не добавит разрешения уже выданным token, пользователю потребуется повторная авторизация.
Шаг 1: зарегистрируйте OAuth-приложение
Откройте Управление OAuth-приложениями, создайте приложение и заполните:- Название, описание, логотип приложения: отображаются на стороне приложения на странице авторизации.
- Тип клиента: для чистого фронтенда, мобильных или десктопных клиентов выберите Public; для сервисов, способных хранить secret на бэкенде, выберите Confidential.
- Адрес обратного вызова: в production используйте HTTPS и зарегистрируйте полный URL, на котором приложение действительно обрабатывает обратный вызов.
- Разрешения: выберите из предоставленного на странице каталога scopes, которые действительно нужны.
client_id. Confidential-клиент хранит client_secret на стороне сервера, его нельзя размещать в HTML, переменных сборки фронтенда или URL. Public-клиент не использует secret при обмене token; даже если ответ регистрации содержит это поле, его нельзя считать учётными данными, которые клиент способен сохранить в тайне.
redirect_uri должен точно совпадать при регистрации, авторизации и обмене token, включая путь, завершающий слеш и параметры запроса. Для каждого аккаунта можно создать не более 20 приложений. Secret отображается только при создании/ротации; после ротации старый secret больше нельзя использовать для обменов, требующих аутентификации клиента.
Шаг 2: кнопка инициирует авторизацию
При каждом нажатии подключения генерируйте новые случайныеstate и code_verifier, вычислите:
state, verifier и адрес обратного вызова в собственной сессии приложения, затем откройте страницу авторизации с параметрами в URL-кодировке:
plain, Public-клиент не может его использовать. Confidential-клиенту также рекомендуется использовать S256; если при инициировании авторизации использовался PKCE, при обмене необходимо передать соответствующий verifier.
После согласия пользователя происходит возврат на redirect_uri, параметры запроса содержат code и возвращённый без изменений state. При отказе возвращаются error=access_denied, описание ошибки и state. Перед обработкой обратного вызова сначала проверьте, что state соответствует текущей сессии. Срок действия кода авторизации составляет 10 минут, и его можно обменять только один раз; после сбоя следует заново инициировать подключение, не обновляйте многократно старый URL обратного вызова.
Шаг 3: обмен OAuth token
Public-клиент выполняет обмен непосредственно из браузера или клиента; Confidential-клиент выполняет обмен на собственном бэкенде. Тело запроса поддерживает form-кодирование, следующие переменные представляют данные, полученные приложением в этой авторизации:client_secret. В настоящее время поддерживается client_secret_post, не считайте HTTP Basic-аутентификацию клиента поддерживаемым способом.
В успешном ответе получите access_token, token_type, expires_in и фактически предоставленный scope. refresh_token доступен только при запросе и одобрении offline_access. Не используйте OAuth access token в качестве API Key для модельного API и не записывайте token, verifier или код авторизации в логи, аналитические события или ссылки для общего доступа.
Шаг 4: чтение информации пользователя и API Key
Сначала запросите UserInfo с помощью OAuth access token:id — идентификатор пользователя; с profile:read или openid можно читать базовые данные (например, username, nickname, avatar, is_verified, date_joined, registration_method); для email требуется email:read, для номера телефона и региона требуется phone:read. Не полагайтесь на то, что неавторизованные поля всегда существуют.
Если нужен существующий API Key и одобрен credentials:read, используйте id из UserInfo как условие фильтрации:
count и items, поле Key — items[*].token, а не data[0].value. user_id=me не является действительным ID пользователя для этого интерфейса. Для многостраничных данных продолжайте чтение с помощью offset/limit, не считайте первую страницу всеми учётными данными.
Выбирайте применимые учётные данные в соответствии с приложением, сервисом и состоянием валидности, не берите вслепую первую запись. Пустой список не означает сбой авторизации; пользователь может ещё не создать подходящий Key. Контроль разрешений OAuth access token и собственные ограничения API Key по области сервисов, квотам и условиям истечения срока действия — это разные ограничения.
Разрешение на чтение API Key означает, что третья сторона может сохранить и использовать его. Отзыв OAuth-запроса или очистка состояния входа приложения не сделают уже скопированный API Key недействительным; пользователю необходимо отдельно отозвать или ротировать этот Key в управлении учётными данными.
Рабочий пример браузера Public / PKCE
Разверните следующую страницу на зарегистрированном вамиREDIRECT_URI, замените CLIENT_ID и адрес обратного вызова. Кнопка инициирует стандартную авторизацию, после возврата на ту же страницу считываются личные данные и количество существующих Key. Пример не отображает и не сохраняет Key; production-приложение использует результаты в соответствии с фактическим назначением. Сначала проверьте на отдельной странице браузера, затем проведите приёмку согласно требованиям iframe далее.
sessionStorage. Production-приложение должно управлять токенами в собственной схеме сессий, обрабатывать истечение срока действия и очищать параметры URL авторизации после получения ответа; основной интерфейс страницы должен сначала отрисовываться, а сбои сети должны влиять только на статус подключения.
iframe на white-label сайте
Клиентский сайт самостоятельно переходит на страницу авторизации
Достаточно использовать стандартные параметры OAuth и собственную обработку callback;window.location.assign() навигирует текущий iframe, а родительская страница остаётся в white-label домене. Не требуется добавлять embed=studio ради иконки или реализовывать протокол сообщений Studio.
Необходимо выполнить следующие условия:
- Страница приложения и страница callback используют HTTPS, фактически доступны и разрешают встраивание через iframe белому родительскому домену; проверьте
Content-Security-Policy: frame-ancestorsиX-Frame-Optionsс обеих сторон. - sandbox разрешает скрипты, формы и возможности origin/хранилища, необходимые странице. При поддержке входа через всплывающее окно также требуются соответствующие возможности всплывающих окон; предпочтительно использовать конфигурацию компонента Website, предоставляемую Studio.
- Браузер разрешает использовать хранилище, необходимое для состояния авторизации, в текущем встроенном сценарии. Состояние входа на white-label сайте и состояние входа в AuthFrontend могут отличаться; не следует предполагать, что вход на white-label сайт означает вход на страницу авторизации.
- Сервис обмена token в callback доступен, а междоменный запрос разрешён для origin приложения; DNS, CORS и HTTP-ошибки обязательно должны отображать состояние, допускающее повторную попытку, и не должны останавливать отрисовку всей страницы.
Использование авторизации текущего аккаунта Studio
В Studio откройте OAuth в «Настройки → Главная → Компоненты сайта», заполнитеclient_id и зарегистрированный адрес callback. Сайт и callback должны использовать один и тот же HTTPS origin и отличаться от origin Studio. Сторонняя страница должна:
- Отправить
acedatacloud:oauth:readyна точный origin родительского сайта, получить и проверитьacedatacloud:oauth:init. - Кнопка генерирует state и PKCE verifier, отправляет
acedatacloud:oauth:authorize(state, S256 challenge); verifier остаётся внутри собственной страницы. - Проверить родительское окно, origin и state, обработать code или error в
acedatacloud:oauth:resultи обменять их через стандартную token endpoint. Studio отображает страницу авторизации в области компонента, после согласия пользователя возвращает код авторизации сообщением, приложению не нужно перенаправление. При отсутствии входа возвращаетсяlogin_required, при отказе возвращаетсяaccess_denied, при тайм-ауте ожидания возвращаетсяauthorization_timeout. Смена аккаунта пересоздаёт iframe приложения и отменяет незавершённые авторизации.
profile:read credentials:read, без offline_access. Не предполагается, что refresh token обязательно будет получен. embed=studio и embed_origin поддерживаются хостом Studio и страницей авторизации, клиентской странице достаточно соблюдать протокол сообщений.
Полный пример кнопки см. в Руководстве по интеграции OAuth для компонентов сайта Studio.
Жизненный цикл, обновление и отзыв
Срок действия access token по умолчанию составляет 15 дней, следует планировать обновление или повторную авторизацию на основеexpires_in каждого ответа; refresh token по умолчанию действует 30 дней, срок зависит от конфигурации сервиса. Не следует жёстко кодировать эти два значения как постоянные гарантии.
После получения offline_access можно вызвать:
Распространённые ошибки и приёмка
Перед поставкой как минимум проверьте: корректный обратный вызов, отказ, ошибочный state, истёкший/уже использованный code, отсутствие Key, сетевой сбой, истечение token, отсутствие необходимого scope, а также первый вход и переключение аккаунта в сценарии iframe. Не сохраняйте в тестовых доказательствах полные code, token или API Key.
Двухэтапная проверка и повторная авторизация
После включения пользователем двухэтапной проверки Ace Data Cloud выполнит на странице авторизации проверку кода аутентификатора или одноразового кода восстановления, а затем передаст код авторизации. Ваше приложение продолжает использовать стандартный поток OAuth и не должно запрашивать, сохранять или пересылать ключи аутентификатора и коды восстановления пользователя. После включения, замены, отключения двухэтапной проверки пользователем или восстановления аккаунта прежняя сессия аккаунта, refresh token и связанные токены авторизации платформы могут стать недействительными. При получении недействительной сессии илиinvalid_grant снова запустите видимый пользователю процесс авторизации, не используйте повторно старый код авторизации и не пытайтесь обходить проверку. Способ аутентификации обычных API Key модели остаётся неизменным; при подозрении на взлом аккаунта следует отдельно проверить и отозвать затронутые API Key.
