code, а потім обмінює його на OAuth access token.
OAuth access token використовується для доступу до інтерфейсів ресурсів облікового запису; для виклику model 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 містить усі назви дозволів, розпізнані платформою, але не означає, що ваша програма може запитувати кожен із них. Під час фактичної авторизації одночасно перевіряється:
- чи можна делегувати дозвіл цьому типу програми;
- чи зареєстрований дозвіл у дозволених областях цієї OAuth-програми;
- чи має поточний користувач запитуваний дозвіл.
invalid_scope. Під час обміну authorization code та оновлення також виконується повторна перевірка; дозволи не доповнюються та не підвищуються автоматично.
Доступні дозволи для звичайних самостійно обслуговуваних програм
Нижче наведено поточний каталог (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:
plain, Public-клієнти не можуть його використовувати. Confidential-клієнтам також рекомендовано використовувати S256; якщо під час ініціювання авторизації використовувався PKCE, під час обміну потрібно обов’язково подати відповідний verifier.
Після згоди користувач повертається на redirect_uri, а параметри запиту містять code і повернений без змін state. У разі відмови повертаються error=access_denied, опис помилки та state. Перед обробкою зворотного виклику спочатку перевірте, що state відповідає поточній сесії. Термін дії коду авторизації становить 10 хвилин, і його можна обміняти лише один раз; після невдачі слід повторно ініціювати підключення, а не неодноразово оновлювати старий URL зворотного виклику.
Крок 3: отримання OAuth token
Public-клієнти обмінюють безпосередньо з браузера або клієнта; 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
Спочатку використайте OAuth access token, щоб надіслати запит UserInfo: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.
sessionStorage. Виробничий застосунок має керувати токенами у власній схемі сесій, обробляти завершення строку дії та очищати параметри URL авторизації після отримання відповіді; головний інтерфейс сторінки має рендеритися першим, а збої мережі мають впливати лише на статус підключення.
iframe на white-label сайті
Клієнтський сайт самостійно переходить на сторінку авторизації
Достатньо використовувати стандартні параметри OAuth і власну обробку зворотного виклику;window.location.assign() здійснює навігацію поточного iframe, а батьківська сторінка залишається на white-label домені. Не потрібно додавати embed=studio заради іконки чи реалізовувати протокол повідомлень Studio.
Необхідно виконати такі умови:
- Сторінка застосунку й сторінка зворотного виклику використовують HTTPS, фактично доступні та дозволяють вбудовування через iframe батьківським white-label доменом; перевірте
Content-Security-Policy: frame-ancestorsіX-Frame-Optionsз обох сторін. - sandbox дозволяє скрипти, форми та можливості джерела/сховища, потрібні сторінці. Для входу через спливне вікно також потрібні відповідні можливості спливних вікон; пріоритетно використовуйте конфігурацію компонента Website, наданого Studio.
- Браузер дозволяє сховище, потрібне для стану авторизації в поточному вбудованому сценарії. Стан входу на white-label сайті та стан входу в AuthFrontend можуть відрізнятися; не слід припускати, що вхід на white-label сайт означає вже виконаний вхід на сторінку авторизації.
- Служба обміну token у зворотному виклику доступна, а міждоменні запити дозволяють джерело застосунку; DNS, CORS і HTTP-помилки обов’язково мають показувати стан із можливістю повторної спроби, не припиняючи рендеринг усієї сторінки.
Використання авторизації поточного облікового запису Studio
У Studio в «Налаштування → Головна → Компоненти сайту» увімкніть OAuth, заповнітьclient_id і зареєстровану адресу зворотного виклику. Сайт і зворотний виклик мають використовувати однакове HTTPS-джерело та відрізнятися від джерела Studio. Стороння сторінка має:
- Надіслати
acedatacloud:oauth:readyдо точного origin батьківського сайту, отримати та перевіритиacedatacloud:oauth:init. - Кнопка генерує state і PKCE verifier, надсилає
acedatacloud:oauth:authorize(state, S256 challenge); verifier залишається на власній сторінці. - Перевірити батьківське вікно, 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 можна викликати:
Поширені помилки та приймання
Перед доставкою щонайменше перевірте: правильний зворотний виклик, відмову, помилковий state, прострочений/вже використаний code, відсутність Key, збій мережі, прострочення token, відсутність потрібного scope, а також перший вхід і перемикання облікового запису в сценаріях iframe. У тестових доказах не зберігайте повний code, token або API Key.
Двоетапна перевірка та повторна авторизація
Після ввімкнення користувачем двоетапної перевірки Ace Data Cloud на сторінці авторизації виконає перевірку коду автентифікатора або одноразового коду відновлення, а потім надасть код авторизації. Ваш застосунок продовжує використовувати стандартний OAuth-процес і не повинен запитувати в користувача, зберігати чи пересилати ключі автентифікатора та коди відновлення. Після ввімкнення, заміни, вимкнення двоетапної перевірки або відновлення облікового запису користувачем попередні сеанси облікового запису, токени оновлення та пов’язані токени авторизації платформи можуть стати недійсними. У разі отримання недійсного сеансу абоinvalid_grant повторно ініціюйте видимий для користувача процес авторизації, не використовуйте старий код авторизації повторно та не намагайтеся обійти перевірку. Спосіб автентифікації звичайних API Key моделі залишається незмінним; у разі підозри на викрадення облікового запису слід окремо перевірити та відкликати уражені API Key.
