Перейти до основного вмісту
Дозвольте користувачам авторизувати вашу програму для доступу до їхнього профілю Ace Data Cloud, передплат сервісів, API Key, використання або замовлень. Використовуйте стандартний Authorization Code + S256 PKCE: програма відкриває сторінку авторизації, після згоди користувача отримує одноразовий 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 містить усі назви дозволів, розпізнані платформою, але не означає, що ваша програма може запитувати кожен із них. Під час фактичної авторизації одночасно перевіряється:
  1. чи можна делегувати дозвіл цьому типу програми;
  2. чи зареєстрований дозвіл у дозволених областях цієї OAuth-програми;
  3. чи має поточний користувач запитуваний дозвіл.
Невідомі, незареєстровані, недозволені для делегування дозволи або дозволи, яких користувач не має, повертають 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:
Public-клієнти повинні надсилати S256 PKCE. Хоча Discovery також містить plain, Public-клієнти не можуть його використовувати. Confidential-клієнтам також рекомендовано використовувати S256; якщо під час ініціювання авторизації використовувався PKCE, під час обміну потрібно обов’язково подати відповідний verifier. Після згоди користувач повертається на redirect_uri, а параметри запиту містять code і повернений без змін state. У разі відмови повертаються error=access_denied, опис помилки та state. Перед обробкою зворотного виклику спочатку перевірте, що state відповідає поточній сесії. Термін дії коду авторизації становить 10 хвилин, і його можна обміняти лише один раз; після невдачі слід повторно ініціювати підключення, а не неодноразово оновлювати старий URL зворотного виклику.

Крок 3: отримання OAuth token

Public-клієнти обмінюють безпосередньо з браузера або клієнта; Confidential-клієнти обмінюють на власному бекенді. Тіло запиту підтримує кодування форми, наведені нижче змінні представляють дані, отримані застосунком під час цієї авторизації:
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:
Поля, що повертаються, залежать від scope: 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.
Зворотний виклик і точка входу в прикладі мають бути в межах одного джерела та однієї вкладки браузера/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-помилки обов’язково мають показувати стан із можливістю повторної спроби, не припиняючи рендеринг усієї сторінки.
Ліва частина сторінки авторизації зчитує Logo OAuth-застосунку; права зчитує favicon/logo цього Site, коли браузер може надати батьківське джерело й батьківський домен проходить перевірку верифікованим сайтом, інакше показується стандартна іконка. Це визначає лише відображення бренду, не створює сеанс входу та не надає клієнтській сторінці доступу до облікового запису. Поточне обмеження: коли для звичайного OAuth в iframe потрібен повторний вхід, після завершення входу все ще є прогалина в процесі повернення на сторінку авторизації. Перед запуском необхідно окремо прийняти сценарії «Auth уже виконано вхід» і «Auth не виконано вхід/строк дії минув». До виправлення й перевірки цієї прогалини для першого входу можна використовувати окрему сторінку для виконання стандартного OAuth або авторизацію через компонент Studio нижче; не обіцяйте, що всі сценарії iframe працюватимуть, спираючись лише на результати тестування у стані виконаного входу.

Використання авторизації поточного облікового запису Studio

У Studio в «Налаштування → Головна → Компоненти сайту» увімкніть OAuth, заповніть client_id і зареєстровану адресу зворотного виклику. Сайт і зворотний виклик мають використовувати однакове HTTPS-джерело та відрізнятися від джерела Studio. Стороння сторінка має:
  1. Надіслати acedatacloud:oauth:ready до точного origin батьківського сайту, отримати та перевірити acedatacloud:oauth:init.
  2. Кнопка генерує state і PKCE verifier, надсилає acedatacloud:oauth:authorize (state, S256 challenge); verifier залишається на власній сторінці.
  3. Перевірити батьківське вікно, 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 можна викликати:
Оновлення повертає нові token, застосунок повинен зберігати найновіші значення. Під час оновлення перевіряється, чи залишається застосунок дійсним, чи доступний користувач, чи все ще надані дозволи. У разі невдачі очистіть власний стан підключення та повторно авторизуйтеся. Поточна реалізація OAuth-оновлення не гарантує, що старий refresh token стане недійсним одразу після оновлення. Не вважайте отримання нового token підтвердженням відкликання старого token і не замінюйте припинення чинних token ротацією secret. Спосіб виклику запиту на відкликання:
Поточна кінцева точка відкликання повертає HTTP 200, але не реалізує негайне анулювання вже виданих JWT. Застосунок повинен очистити збережені ним token і не може вважати 200 доказом того, що всі видані token або API Key стали недійсними. API Key, які були скомпрометовані або скопійовані, слід окремо відкликати або ротувати відповідні облікові дані.

Поширені помилки та приймання

Перед доставкою щонайменше перевірте: правильний зворотний виклик, відмову, помилковий state, прострочений/вже використаний code, відсутність Key, збій мережі, прострочення token, відсутність потрібного scope, а також перший вхід і перемикання облікового запису в сценаріях iframe. У тестових доказах не зберігайте повний code, token або API Key.

Двоетапна перевірка та повторна авторизація

Після ввімкнення користувачем двоетапної перевірки Ace Data Cloud на сторінці авторизації виконає перевірку коду автентифікатора або одноразового коду відновлення, а потім надасть код авторизації. Ваш застосунок продовжує використовувати стандартний OAuth-процес і не повинен запитувати в користувача, зберігати чи пересилати ключі автентифікатора та коди відновлення. Після ввімкнення, заміни, вимкнення двоетапної перевірки або відновлення облікового запису користувачем попередні сеанси облікового запису, токени оновлення та пов’язані токени авторизації платформи можуть стати недійсними. У разі отримання недійсного сеансу або invalid_grant повторно ініціюйте видимий для користувача процес авторизації, не використовуйте старий код авторизації повторно та не намагайтеся обійти перевірку. Спосіб автентифікації звичайних API Key моделі залишається незмінним; у разі підозри на викрадення облікового запису слід окремо перевірити та відкликати уражені API Key.