> ## 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) + 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. **Назва / опис / логотип застосунку**: відображатимуться на сторінці згоди користувача на авторизацію.
2. **Тип клієнта (Client Type)**:
   * **Конфіденційний (confidential)** — у вас є бекенд, де можна безпечно зберігати `client_secret` (вебсервіс, бекенд-сервіс).
   * **Публічний (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: виклик інтерфейсів за допомогою Access Token

Достатньо помістити токен у заголовок `Authorization: Bearer`.

**Отримання інформації про користувача (UserInfo, поля фільтруються відповідно до авторизованого scope):**

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

**Виклик інтерфейсу ресурсів платформи** (`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, мати однакове походження (протокол, домен і порт) та мати інше походження, ніж Studio.
У конфігурації не можна вказувати `client_secret`; секрет застосунку може зберігатися лише на сторонньому бекенді.

Компонент запитує дозволи `profile:read credentials:read`. Кожен відвідувач повинен надати згоду окремо; налаштування компонента власником сайту не означає авторизацію відвідувача.
Стороння сторінка генерує випадкові `state` і PKCE verifier, надсилаючи до Studio S256 challenge. 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.