Интеграция «Войти с Ace Data Cloud» (OAuth 2.0)

Добавьте в свой продукт поддержку «Войти с Ace Data Cloud» и после авторизации пользователя от его имени читайте и записывайте его ресурсы Ace Data Cloud (профиль, API Token, подписки, использование, заказы и т. д.). В основе лежит стандартный OAuth 2.0 Authorization Code Flow (Authorization Code) + PKCE, интеграция полностью идентична входу через GitHub / Google — можно напрямую использовать любую имеющуюся у вас OAuth-клиентскую библиотеку.

Подходящие сценарии: вы разрабатываете стороннее приложение / Agent / MCP-клиент / автоматизированный рабочий процесс и хотите, чтобы пользователи входили в один клик с помощью аккаунта Ace Data Cloud и при необходимости получали доступ к своим ресурсам на платформе, без необходимости вручную копировать и вставлять API Key.

Краткий справочник терминов и эндпоинтов

Все эндпоинты находятся на https://auth.acedata.cloud, актуальные адреса всегда можно получить через эндпоинт обнаружения (Discovery):

curl https://auth.acedata.cloud/.well-known/oauth-authorization-server

Назначение	Эндпоинт
Документ обнаружения (Discovery)	`GET /.well-known/oauth-authorization-server`
Страница авторизации пользователя (переход в браузере)	`GET https://auth.acedata.cloud/oauth2/authorize`
Эндпоинт токенов (получение / обновление token)	`POST https://auth.acedata.cloud/oauth2/token`
Отзыв токена	`POST https://auth.acedata.cloud/oauth2/revoke`
Информация о пользователе (UserInfo)	`GET https://auth.acedata.cloud/api/v1/users/me`
Управление регистрацией приложений (самообслуживание)	`https://auth.acedata.cloud/user/oauth-apps`

Поддерживаемые возможности: response_type=code, grant_types=authorization_code, refresh_token, code_challenge_methods=S256, plain, способы аутентификации клиента client_secret_post (конфиденциальные клиенты) / none (публичные PKCE-клиенты).

Области разрешений (Scope)

Запрашивайте по принципу «минимальных привилегий»: пользователь увидит на странице авторизации каждый запрашиваемый вами доступ. Идентификационные (совместимые с OIDC)

Scope	Значение	Поля, возвращаемые `/users/me`
`openid`	Уникальный идентификатор пользователя	`id`
`profile`	Основные данные	`username`、`nickname`、`avatar`、`is_verified`、`date_joined`
`email`	Электронная почта	`email`
`phone`	Номер телефона (чувствительные данные)	`phone`、`region`

Ресурсы платформы

Scope	Значение
`applications:read` / `applications:write`	Чтение / изменение подписок и лимитов сервиса пользователя
`credentials:read` / `credentials:write`	Чтение / создание и отзыв API Token пользователя
`usage:read`	Чтение истории вызовов пользователя
`orders:read` / `orders:write`	Чтение заказов / оформление заказа и инициирование оплаты

Агрегированные (автоматически раскрываются)

Scope	Раскрывается в
`platform:read`	`applications:read` + `credentials:read` + `usage:read` + `orders:read`
`platform:write`	`applications:write` + `credentials:write` + `orders:write`
`platform`	`platform:read` + `platform:write`

Особые

Scope	Значение
`offline_access`	Выдаёт Refresh Token (если не запрашивать, выдаётся только Access Token, после истечения срока требуется повторная авторизация)

Типичные комбинации: сторонний «вход в один клик» =openid profile; MCP / IDE-клиенту нужна автоматическая настройка Key =openid profile credentials:read credentials:write; полная панель управления =openid profile email platform offline_access.

Шаг 1: зарегистрируйте OAuth-приложение

Откройте auth.acedata.cloud/user/oauth-apps → «Создать приложение» и заполните:

Название / описание / Logo приложения: будут отображаться на странице согласия пользователя.
Тип клиента (Client Type):
- Конфиденциальный (confidential) — у вас есть бэкенд и вы можете безопасно хранить client_secret (Web-сервис, бэкенд-сервис).
- Публичный (public) — чистый фронтенд / десктоп / CLI / мобильное приложение, не может хранить секрет, обязательно используйте PKCE.
Адреса обратного вызова (Redirect URIs): адрес, на который пользователь перенаправляется после завершения авторизации; должен полностью совпадать с redirect_uri, переданным при запуске авторизации; можно указать несколько.
Области разрешений (Scopes): отметьте нужные вам scope из предыдущего раздела.

После сохранения вы получите client_id; конфиденциальным клиентам также однократно отображается client_secret — немедленно сохраните его, после закрытия повторно просмотреть его нельзя (на странице деталей можно заново сгенерировать через «Rotate Secret», старый секрет немедленно станет недействительным).

Каждый аккаунт может создать не более 20 OAuth-приложений.

Шаг 2: перенаправьте пользователя на страницу авторизации

В вашем приложении перенаправьте браузер пользователя на страницу авторизации, добавив параметры запроса:

https://auth.acedata.cloud/oauth2/authorize
  ?response_type=code
  &client_id=<你的 client_id>
  &redirect_uri=<你注册的回调地址>
  &scope=openid%20profile%20credentials:read
  &state=<随机防 CSRF 串>
  &code_challenge=<PKCE 挑战值>          # 公开客户端必填
  &code_challenge_method=S256            # 公开客户端必填

state: самостоятельно сгенерированная случайная строка, возвращается в исходном виде при обратном вызове и используется для защиты от CSRF, обязательно проверяйте.
PKCE (обязательно для публичных клиентов, также рекомендуется для конфиденциальных): сначала сгенерируйте случайный code_verifier, затем вычислите code_challenge = BASE64URL( SHA256( code_verifier ) ), поместите code_challenge в URL авторизации, а code_verifier сохраните у себя для использования на шаге 4.

После входа пользователя и нажатия «Согласиться» браузер будет перенаправлен обратно:

<redirect_uri>?code=<授权码>&state=<原样返回的 state>

Если пользователь отказался: <redirect_uri>?error=access_denied&error_description=...&state=....

Срок действия кода авторизации составляет 10 минут, и его можно использовать только один раз.

Шаг 3: обменяйте код авторизации на токены

На вашем бэкенде (конфиденциальный клиент) или в клиенте (публичный PKCE-клиент) вызовите эндпоинт токенов с помощью code. Конфиденциальный клиент (с client_secret):

curl -X POST https://auth.acedata.cloud/oauth2/token \
  -d grant_type=authorization_code \
  -d code=<上一步拿到的 code> \
  -d client_id=<你的 client_id> \
  -d client_secret=<你的 client_secret> \
  -d redirect_uri=<和第 2 步完全一致的回调地址>

Публичный клиент (PKCE, без client_secret):

curl -X POST https://auth.acedata.cloud/oauth2/token \
  -d grant_type=authorization_code \
  -d code=<code> \
  -d client_id=<你的 client_id> \
  -d code_verifier=<第 2 步生成的 code_verifier> \
  -d redirect_uri=<回调地址>

Успешный ответ (refresh_token появляется только при запросе offline_access):

{
  "access_token": "<JWT>",
  "token_type": "Bearer",
  "expires_in": 1296000,
  "scope": "openid profile credentials:read",
  "refresh_token": "<JWT，仅 offline_access 时>"
}

access_token — это JWT, содержащий заявление scope; срок действия 15 дней (число секунд expires_in). Срок действия Refresh Token — 30 дней.

Шаг 4: Вызовите API с помощью Access Token

Просто поместите токен в заголовок Authorization: Bearer. Получение информации о пользователе (UserInfo, поля фильтруются согласно авторизованному scope):

curl https://auth.acedata.cloud/api/v1/users/me \
  -H "Authorization: Bearer <access_token>"

Вызов API ресурсов платформы (platform.acedata.cloud, авторизация по scope). Например, уже получен credentials:read:

curl "https://platform.acedata.cloud/api/v1/credentials/?user_id=<UserInfo返回的id>" \
  -H "Authorization: Bearer <access_token>"

Бэкенд платформы проверяет заявление scope в JWT — токен может получать доступ только к ресурсам, авторизованным пользователем. При доступе к неавторизованному ресурсу будет возвращён 403.

Обновление токена

После истечения Access Token используйте Refresh Token, чтобы получить пару новых токенов (требуется, чтобы изначально был запрошен offline_access):

curl -X POST https://auth.acedata.cloud/oauth2/token \
  -d grant_type=refresh_token \
  -d refresh_token=<你的 refresh_token>

Структура ответа такая же, как на шаге 3; scope сохраняется без изменений из исходной авторизации. После обновления старый Refresh Token становится недействительным (ротация), сохраните новый.

Отзыв токена

curl -X POST https://auth.acedata.cloud/oauth2/revoke \
  -d token=<access_token 或 refresh_token>

Реальный пример: именно так подключены наши собственные MCP-серверы

Подключения «Sign in with Ace Data Cloud», отображаемые в Claude Desktop / Cursor для более чем 15 MCP-серверов Ace Data Cloud (NanoBanana, Midjourney, Suno, Seedance, Kling…), используют именно этот процесс: все они зарегистрированы как OAuth-приложения типа публичное (PKCE), запрашивают scope, связанные с credentials, и после авторизации пользователя MCP-серверы могут вызывать api.acedata.cloud от имени пользователя — пользователю не нужно вручную вставлять API Key. Ваш способ подключения полностью такой же, как у них.

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

Формат ответа об ошибке: { "error": "<code>", "error_description": "<читаемое человеком описание>" }:

error	Значение / проверка
`invalid_request`	Отсутствующий или недопустимый параметр (например, не передан `code` / `client_id`)
`invalid_client`	`client_id` не существует, приложение отключено или неверен `client_secret`
`invalid_grant`	Код авторизации не существует / истёк (>10 минут) / уже использован / не пройдена проверка PKCE / `redirect_uri` не совпадает с указанным при авторизации
`access_denied`	Пользователь нажал «Отклонить» на странице авторизации
`unsupported_grant_type`	`grant_type` не является `authorization_code` или `refresh_token`

Краткая сводка ограничений

Пункт	Значение
Максимальное число OAuth-приложений для аккаунта	20
Срок действия кода авторизации	10 минут, однократное использование
Срок действия Access Token	15 дней
Срок действия Refresh Token	30 дней (ротация)
`redirect_uri`	Должен точно совпадать с зарегистрированным значением
`client_secret`	Отображается только один раз при создании / ротации, на сервере хранится в виде хеша SHA-256

Встраивание стороннего OAuth-приложения на главную страницу Studio

В Studio можно включить OAuth через «Настройки → Главная страница → Компоненты сайта», настроив client_id стороннего приложения и зарегистрированный адрес обратного вызова. Сайт и обратный вызов должны использовать HTTPS, иметь один и тот же origin (протокол, домен и порт) и иметь origin, отличный от Studio. В конфигурации нельзя указывать client_secret; ключ приложения может храниться только на стороннем бэкенде. Компонент запрашивает разрешения profile:read credentials:read. Каждый посетитель должен дать согласие отдельно; настройка компонента владельцем сайта не означает авторизацию посетителя. Сторонняя страница генерирует случайные state и PKCE verifier, отправляя S256 challenge в Studio. Studio размещает официальную страницу авторизации в области компонента, после согласия пользователя сторонняя сторона получает одноразовый код авторизации, вызывает token endpoint для обмена на OAuth access token, а затем получает доступ к GET https://platform.acedata.cloud/api/v1/credentials/?user_id=<用户ID> для чтения существующего API Key. ID пользователя берётся из id, возвращённого на предыдущем шаге GET https://auth.acedata.cloud/api/v1/users/me; интерфейс списка учётных данных не принимает user_id=me. Studio не передаёт сторонней стороне собственный токен входа и не считывает и не внедряет напрямую Key пользователя. Публичные клиенты обязаны использовать S256 PKCE. При обмене token необходимо передать redirect_uri, полностью совпадающий с запросом авторизации. Код авторизации можно обменять только один раз. Перед авторизацией проверяется, зарегистрирован ли адрес обратного вызова. Сторонняя страница должна реализовать протокол сообщений; любая готовая веб-страница не может быть автоматически подключена, просто указав URL. Полный пример см. в руководстве по подключению OAuth-компонента Studio. Авторизация на чтение API Key равнозначна разрешению сторонней стороне сохранять и использовать этот Key. Отмена OAuth-авторизации не делает недействительным Key, уже скопированный сторонней стороной; пользователь должен отдельно отозвать или ротировать Key.

Начало работы

AI Чат

AI Изображение

AI Видео

AI Аудио

Веб и данные

CAPTCHA

Идентичность

Coding

Другие руководства

Интеграция «Войти с Ace Data Cloud» (OAuth 2.0)

Краткий справочник терминов и эндпоинтов

Области разрешений (Scope)

Шаг 1: зарегистрируйте OAuth-приложение

Шаг 2: перенаправьте пользователя на страницу авторизации

Шаг 3: обменяйте код авторизации на токены

Шаг 4: Вызовите API с помощью Access Token

Обновление токена

Отзыв токена

Реальный пример: именно так подключены наши собственные MCP-серверы

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

Краткая сводка ограничений

Встраивание стороннего OAuth-приложения на главную страницу Studio

​Краткий справочник терминов и эндпоинтов

​Области разрешений (Scope)

​Шаг 1: зарегистрируйте OAuth-приложение

​Шаг 2: перенаправьте пользователя на страницу авторизации

​Шаг 3: обменяйте код авторизации на токены

​Шаг 4: Вызовите API с помощью Access Token

​Обновление токена

​Отзыв токена

​Реальный пример: именно так подключены наши собственные MCP-серверы

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

​Краткая сводка ограничений

​Встраивание стороннего OAuth-приложения на главную страницу Studio

Краткий справочник терминов и эндпоинтов

Области разрешений (Scope)

Шаг 1: зарегистрируйте OAuth-приложение

Шаг 2: перенаправьте пользователя на страницу авторизации

Шаг 3: обменяйте код авторизации на токены

Шаг 4: Вызовите API с помощью Access Token

Обновление токена

Отзыв токена

Реальный пример: именно так подключены наши собственные MCP-серверы

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

Краткая сводка ограничений

Встраивание стороннего OAuth-приложения на главную страницу Studio