OAuth 2.0

OAuth 2.0 — це сучасний стандартний протокол авторизації. Він дозволяє інтеграції отримувати доступ до даних користувача в іншому сервісі без передачі логіна та пароля, використовуючи систему токенів (Access Token та Refresh Token). Блок OAuth 2.0 автоматизує повний OAuth-флоу: від авторизації користувача до отримання, зберігання та оновлення токенів.

Навігація

1. Призначення, розташування та особливість
2. Вибір Grant Type
3. Налаштування блоку Authorization Code
4. Налаштування блоку Client Credentials
5. Вкладка Test (Дебаггер)
6. Додавання акаунту та ініціалізація запуску
7. FAQ

Призначення, розташування та особливість

─────────────────────────────────────────────────────────────-

Блок використовується виключно у флоу Authentication. Його головна задача — отримати Access Token та автоматично підставляти його у всі наступні запити. Також цей блок вміє самостійно оновлювати токен (Refresh Token), якщо API це підтримує.  

Як це працює:

1. Ви додаєте блок у Authentication Flow та налаштовуєте посилання для авторизації (Auth URL, Token URL).
2. У вікні Flow Test ви ініціюєте підключення: система перенаправляє вас на сайт сервісу для входу та надання дозволів.
3. Платформа автоматично перехоплює код авторизації, обмінює його на токен (Access Token) і безпечно зберігає для подальшого використання.

Вибір Grant Type

─────────────────────────────────────────────────────────────-

Перше, що потрібно зробити — обрати сценарій роботи у полі Grant type. Від цього залежить набір подальших налаштувань.  

1. Authorization Code:

• Для чого: Класичний варіант, коли користувач має натиснути кнопку, побачити спливаюче вікно, залогінитись у сервісі та натиснути "Дозволити".
• Ключові елементи: Auth URL, Access Token URL, Refresh Token URL.

2. Client Credentials:

• Для чого: Серверна авторизація (Machine-to-Machine). Без участі живого користувача. Доступ надається на основі пари Client ID + Secret.
  
• Ключові елементи: Тільки Access Token URL.
  

Налаштування блоку (Authorization Code)

─────────────────────────────────────────────────────────────-

Якщо обрано цей тип, блок розгортає повний набір полів для налаштування циклу OAuth.

1 -> App settings (Налаштування клієнта)
Перемикач визначає, чиї ключі додатку будуть використовуватись:

• Увімкнено (ON): Ви як розробник "зашиваєте" Client Id та Secret всередину інтеграції. Вони будуть спільними для всіх користувачів (Global App).
• Вимкнено (OFF): Кожен користувач повинен буде при підключенні ввести свій власний Client Id та Secret.

При увімкненому App settings з’являються додаткові поля:

• 1.1 -> Client Id — ідентифікатор застосунку (може працювати в режимі поля TXT / EXP).
• 1.2 -> Secret — секрет застосунку (може працювати в режимі поля TXT / EXP).
• 1.3 -> Callback URL — посилання, на яке сервіс поверне користувача після логіну (це поле часто називається "Redirect URIs").

2 -> Auth URL: посилання, куди система перенаправить користувача для авторизації, (наприклад: https://build.fillout.com/authorize/oauth)

3 -> Auth Request Args: Параметри, що додаються до посилання. За замовчуванням система пропонує стандартний набір:

• response_type = code
• access_type = offline (важливо для отримання Refresh Token)
• prompt = consent

Ви можете додавати власні параметри через кнопку "+ Add Item". Також кожен параметр можна увімкнути / вимкнути галочкою.

4 -> Scopes (необов'язково): перелік дозволів, які запитуються у користувача. Формат і синтаксис залежать від API провайдера.

5 -> Access Token URL: посилання, за яким система обміняє отриманий від користувача "код" на реальний токен доступу (access token). Наприклад: https://server.fillout.com/public/oauth/accessToken. 

6 -> Access Token Request Args: додаткові аргументи для запиту access token. Для кожного аргументу задається Key / Value та Send In (де передавати параметр):

• Request URL - як Query parameters
• Request Body - як Form data / JSON
• Request Headers - як заголовки

7 -> Refresh Token URL: посилання для оновлення access token (якщо підтримується). Якщо API видає токени, що живуть короткий час (наприклад, 1 годину), заповнення цього поля дозволить платформі автоматично оновлювати доступ без участі користувача.

8 -> Refresh Token Request Args: аргументи для запиту оновлення токена.
Структура і логіка аналогічні Access Token Request Args.

9 -> Перемикач режиму полів TXT / EXP:

Простий варіант (TXT режим) - все обробляється як текст.

Просунутий варіант (EXP режим) - вміст обробляється як повноцінний вираз (Expression). Дозволяє застосувати логічні оператори та функції безпосередньо в полі вибору. Наприклад, «/» у режимі TXT - це роздільник, а в режимі EXP - ділення.

Налаштування блоку (Client Credentials)

─────────────────────────────────────────────────────────────-

Спрощений режим для серверних інтеграцій. Використовується для доступу "машина-машина" без участі користувача.

Доступні поля для налаштування:

1 -> Scopes: області доступу (права), які запитує інтеграція. Формат і синтаксис залежать від API провайдера.

2 -> Access Token URL: посилання, за яким система обміняє отриманий від користувача "код" на реальний токен доступу (access token). Наприклад: https://server.fillout.com/public/oauth/accessToken. 

3 -> Access Token Request Args: аргументи для запиту access token. Для кожного аргументу задається Key / Value та Send In (де передавати параметр):  

• Request URL - як Query parameters
• Request Body - як Form data / JSON
• Request Headers - як заголовки

Вкладка Test (Дебаггер)

─────────────────────────────────────────────────────────────-

Блок OAuth 2.0 має потужну вкладку Test для діагностики. Оскільки процес авторизації відбувається "під капотом", тут ви можете побачити, що саме відбулося:

1 -> Current Account: Статус підключеного акаунту, отриманий Access Token та час його створення.

2 -> Last Request: Повний текст останнього запиту, який платформа відправила сервісу (заголовки, тіло, URL).

3 -> Last Response: Відповідь сервера. Якщо авторизація не проходить, саме тут ви побачите текст помилки від API (наприклад, invalid_grant або redirect_uri_mismatch).

4 -> Execution Results: Результат виконання флоу авторизації.

Додавання акаунту та ініціалізація запуску (Flow Test)

─────────────────────────────────────────────────────────────-

Після того, як ви налаштували блок OAuth 2.0 як метод автентифікації, необхідно створити реальне підключення та ініціалізувати тестовий запуск, щоб система «побачила» ці дані.

Цей порядок є обовʼязковим для коректної роботи OAuth 2.0-автентифікації.

Покрокова інструкція підключення:

1 -> Кнопка Flow Test: У нижній лівій частині екрану натисніть кнопку Flow Test. Відкриється панель налаштування тесту, де проводиться підключення акаунту та запуск інтеграції.

2 -> Кнопка Add New Account: Натисніть Add New Account, щоб додати нове підключення для авторизації.

3 -> Заповнення даних: У вікні, що з'явилося, заповніть наступні поля:

• 4 -> Name: вкажіть зрозуміле ім'я для вашого підключення (наприклад, "Prod auth"), для майбутньої швидкої ідентифікації.
• 5 -> Callback URL (Redirect URIs): вже заповнений — скопіюйте посилання з вікна підключення та обов'язково додайте його в налаштуваннях вашого додатку на стороні сервісу (API).
• 6 -> Client Id та  Client Secret: скопіюйте ключі з сервісу та вставте їх у відповідні поля вікна (якщо вони не були задані глобально в App Settings).

7 -> Save: Натисніть кнопку Save всередині спливаючого вікна, щоб зберегти введені дані нового акаунту. З'явиться кнопка для авторизації Get Access Token.

8 -> Get Access Token: Натисніть кнопку Get Access Token для авторизації. Відкриється спливаюче вікно сервісу -> увійдіть в акаунт -> надайте дозволи.

9 -> Отримання токена: Після успішної авторизації в акаунті з’являється Access Token, дата і час створення, та можливість відразу видалити (Remove) цей токен.
Важливо: Вікно не закривається автоматично. Після збереження закрийте вікно вручну, щоб повернутися до інтерфейсу.

10 -> Вибір акаунту: У списку акаунтів оберіть щойно створений акаунт.

11 -> Кнопка Save (у Flow Test): Натисніть Save на панелі Flow Test. Це закріпить обраний акаунт за поточною сесією розробки.

12 -> Кнопка Run Test: Натисніть Run Test, щоб ініціалізувати запуск інтеграції. Це критично важливий крок: саме на цьому етапі платформа  робить введені дані акаунта доступними для інших флоу ( Account Validation, Main Action тощо).

FAQ

─────────────────────────────────────────────────────────────

1. Отримую помилку "redirect_uri_mismatch". Що робити?
Це найпоширеніша помилка. Вона означає, що посилання Callback URL, яке ви бачите у вікні підключення акаунту, не додано до списку дозволених "Redirect URIs" у налаштуваннях вашого додатку на стороні API сервісу. Вони мають співпадати до символу.

2. Чи потрібно мені додавати токен у HTTP Request вручну?
Ні. Блок OAuth 2.0 автоматично додає отриманий Access Token у заголовок Authorization: Bearer ... до всіх запитів цієї інтеграції.

3. Що таке Scopes?
Це права доступу. Наприклад, read_contacts, write_orders. Якщо ви вкажете скоупи, яких немає у вашого додатку, або які ви забули налаштувати на стороні сервісу, авторизація може видати помилку invalid_scope.

4. Чи оновлюється access token автоматично?
Так, якщо налаштовано Refresh Token URL та аргументи.

5. Коли обирати Client Credentials замість Authorization Code?
Коли інтеграція не прив’язана до конкретного користувача і працює сервер–сервер.