Інтеграція «Увійти за допомогою 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):

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 → «Створити застосунок», заповніть:

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

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

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

Виклик інтерфейсу ресурсів платформи (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, мати однакове походження (протокол, домен і порт) та мати інше походження, ніж 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=<用户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.

Getting Started

AI Чат

AI Зображення

AI Відео

AI Аудіо

Веб і дані

CAPTCHA

Ідентичність

Coding

Інші посібники

Інтеграція «Увійти за допомогою Ace Data Cloud» (OAuth 2.0)

Швидка довідка термінів і кінцевих точок

Області дозволів (Scope)

Крок 1: зареєструйте OAuth-застосунок

Крок 2: перенаправте користувача на сторінку авторизації

Крок 3: обміняйте код авторизації на токен

Крок 4: виклик інтерфейсів за допомогою Access Token

Оновлення токена

Відкликання токена

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

Поширені помилки

Швидкий довідник обмежень

Вбудовування стороннього OAuth-застосунку на головній сторінці Studio

​Швидка довідка термінів і кінцевих точок

​Області дозволів (Scope)

​Крок 1: зареєструйте OAuth-застосунок

​Крок 2: перенаправте користувача на сторінку авторизації

​Крок 3: обміняйте код авторизації на токен

​Крок 4: виклик інтерфейсів за допомогою Access Token

​Оновлення токена

​Відкликання токена

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

​Поширені помилки

​Швидкий довідник обмежень

​Вбудовування стороннього OAuth-застосунку на головній сторінці Studio

Швидка довідка термінів і кінцевих точок

Області дозволів (Scope)

Крок 1: зареєструйте OAuth-застосунок

Крок 2: перенаправте користувача на сторінку авторизації

Крок 3: обміняйте код авторизації на токен

Крок 4: виклик інтерфейсів за допомогою Access Token

Оновлення токена

Відкликання токена

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

Поширені помилки

Швидкий довідник обмежень

Вбудовування стороннього OAuth-застосунку на головній сторінці Studio