> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Интеграция «Войти с 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):

```bash theme={null}
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](https://auth.acedata.cloud/user/oauth-apps) → «Создать приложение» и заполните:

1. **Название / описание / Logo приложения**: будут отображаться на странице согласия пользователя.
2. **Тип клиента (Client Type)**:
   * **Конфиденциальный (confidential)** — у вас есть бэкенд и вы можете безопасно хранить `client_secret` (Web-сервис, бэкенд-сервис).
   * **Публичный (public)** — чистый фронтенд / десктоп / CLI / мобильное приложение, **не может** хранить секрет, обязательно используйте **PKCE**.
3. **Адреса обратного вызова (Redirect URIs)**: адрес, на который пользователь перенаправляется после завершения авторизации; **должен полностью совпадать с `redirect_uri`, переданным при запуске авторизации**; можно указать несколько.
4. **Области разрешений (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):**

```bash theme={null}
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):**

```bash theme={null}
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`):

```json theme={null}
{
  "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):**

```bash theme={null}
curl https://auth.acedata.cloud/api/v1/users/me \
  -H "Authorization: Bearer <access_token>"
```

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

```bash theme={null}
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`):

```bash theme={null}
curl -X POST https://auth.acedata.cloud/oauth2/token \
  -d grant_type=refresh_token \
  -d refresh_token=<你的 refresh_token>
```

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

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

```bash theme={null}
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": "&lt;читаемое человеком описание>" }`:

| 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=&lt;用户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](https://github.com/AceDataCloud/Nexior/blob/main/docs/integrations/studio-home-oauth.md).

**Авторизация на чтение API Key равнозначна разрешению сторонней стороне сохранять и использовать этот Key. Отмена OAuth-авторизации не делает недействительным Key, уже скопированный сторонней стороной;
пользователь должен отдельно отозвать или ротировать Key.**


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.