Перейти к основному содержанию
Позвольте пользователям авторизовать ваше приложение для доступа к их профилю Ace Data Cloud, подпискам на сервисы, API Key, использованию или заказам. Используйте стандартный Authorization Code + S256 PKCE: приложение открывает страницу авторизации, после согласия пользователя получает одноразовый 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 содержит все распознаваемые платформой названия разрешений, но не означает, что ваше приложение может запросить каждое из них. При фактической авторизации одновременно проверяется:
  1. разрешено ли делегировать это разрешение данному типу приложения;
  2. зарегистрировано ли это разрешение в допустимых scope данного OAuth-приложения;
  3. имеет ли текущий пользователь запрошенное разрешение.
Неизвестные, незарегистрированные, запрещённые к делегированию разрешения или разрешения, которых нет у пользователя, возвращают 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-кодировке:
Public-клиент обязан отправлять S256 PKCE. Хотя Discovery также указывает plain, Public-клиент не может его использовать. Confidential-клиенту также рекомендуется использовать S256; если при инициировании авторизации использовался PKCE, при обмене необходимо передать соответствующий verifier. После согласия пользователя происходит возврат на redirect_uri, параметры запроса содержат code и возвращённый без изменений state. При отказе возвращаются error=access_denied, описание ошибки и state. Перед обработкой обратного вызова сначала проверьте, что state соответствует текущей сессии. Срок действия кода авторизации составляет 10 минут, и его можно обменять только один раз; после сбоя следует заново инициировать подключение, не обновляйте многократно старый URL обратного вызова.

Шаг 3: обмен OAuth token

Public-клиент выполняет обмен непосредственно из браузера или клиента; Confidential-клиент выполняет обмен на собственном бэкенде. Тело запроса поддерживает form-кодирование, следующие переменные представляют данные, полученные приложением в этой авторизации:
Confidential-клиенту также необходимо добавить на стороне сервера поле формы 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:
Возвращаемые поля зависят от scope: 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 далее.
Callback и точка входа в примере должны находиться в одном origin, в той же вкладке браузера/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-ошибки обязательно должны отображать состояние, допускающее повторную попытку, и не должны останавливать отрисовку всей страницы.
Левая сторона страницы авторизации читает Logo OAuth-приложения; правая сторона читает favicon/logo этого Site, когда браузер может предоставить родительский origin и родительский домен проходит проверку подтверждённого сайта, в противном случае отображается иконка по умолчанию. Это определяет только отображение бренда, не создаёт сеанс входа и не предоставляет клиентской странице права доступа к аккаунту. Текущее ограничение: при необходимости повторного входа для обычного OAuth внутри iframe в процессе продолжения возврата на страницу авторизации после завершения входа всё ещё есть пробел. Перед запуском необходимо отдельно принять сценарии «Auth уже выполнен вход» и «Auth не выполнен вход/истёк». До исправления и проверки этого пробела для первого входа можно использовать отдельную страницу для выполнения стандартного OAuth или применить авторизацию через компонент Studio ниже; не обещайте, что все сценарии iframe работают, основываясь только на результатах тестирования при уже выполненном входе.

Использование авторизации текущего аккаунта Studio

В Studio откройте OAuth в «Настройки → Главная → Компоненты сайта», заполните client_id и зарегистрированный адрес callback. Сайт и callback должны использовать один и тот же HTTPS origin и отличаться от origin Studio. Сторонняя страница должна:
  1. Отправить acedatacloud:oauth:ready на точный origin родительского сайта, получить и проверить acedatacloud:oauth:init.
  2. Кнопка генерирует state и PKCE verifier, отправляет acedatacloud:oauth:authorize (state, S256 challenge); verifier остаётся внутри собственной страницы.
  3. Проверить родительское окно, 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 можно вызвать:
Обновление возвращает новые token, приложение должно сохранять актуальные значения. При обновлении проверяется, остаётся ли приложение действительным, доступен ли пользователь и сохраняются ли разрешения. При ошибке очистите собственное состояние подключения и выполните повторную авторизацию. Текущая реализация OAuth-обновления не гарантирует, что старый refresh token немедленно становится недействительным после обновления. Не считайте получение нового token признаком того, что старый token был отозван, и не заменяйте прекращение действия существующих token ротацией secret. Запрос отзыва вызывается следующим образом:
Текущая конечная точка отзыва возвращает HTTP 200, но не реализует немедленную недействительность уже выданных JWT. Приложение должно очистить сохранённые им token и не может считать 200 доказательством того, что все выданные token или API Key стали недействительными. API Key, которые были раскрыты или скопированы, следует отдельно отозвать или ротировать соответствующие учётные данные.

Распространённые ошибки и приёмка

Перед поставкой как минимум проверьте: корректный обратный вызов, отказ, ошибочный state, истёкший/уже использованный code, отсутствие Key, сетевой сбой, истечение token, отсутствие необходимого scope, а также первый вход и переключение аккаунта в сценарии iframe. Не сохраняйте в тестовых доказательствах полные code, token или API Key.

Двухэтапная проверка и повторная авторизация

После включения пользователем двухэтапной проверки Ace Data Cloud выполнит на странице авторизации проверку кода аутентификатора или одноразового кода восстановления, а затем передаст код авторизации. Ваше приложение продолжает использовать стандартный поток OAuth и не должно запрашивать, сохранять или пересылать ключи аутентификатора и коды восстановления пользователя. После включения, замены, отключения двухэтапной проверки пользователем или восстановления аккаунта прежняя сессия аккаунта, refresh token и связанные токены авторизации платформы могут стать недействительными. При получении недействительной сессии или invalid_grant снова запустите видимый пользователю процесс авторизации, не используйте повторно старый код авторизации и не пытайтесь обходить проверку. Способ аутентификации обычных API Key модели остаётся неизменным; при подозрении на взлом аккаунта следует отдельно проверить и отозвать затронутые API Key.