Two-Factor Authentication | СКАРБ Cloud

Authorization/Two-Factor Authentication

Цей розділ описує механізм автентифікації користувачів в API за допомогою двофакторної автентифікації (2FA). Процес входу залежить від налаштувань вашого облікового запису:

Якщо 2FA вимкнено (стандартний вхід): процес авторизації виконується в один крок. Ви надсилаєте запит із логіном та паролем і одразу отримуєте постійний токен доступу для подальшої роботи (детальніше див. /account/login/).
Якщо 2FA увімкнено (безпечний вхід): система використовує двоступеневий процес входу. Після перевірки логіна та пароля сервер повертає тимчасовий токен попередньої авторизації (pre_auth_token). Для завершення входу та отримання основного токена доступу необхідно виконати другий крок — підтвердити дію за допомогою 6-значного коду з вашого додатка-автентифікатора (наприклад, Google Authenticator).

Схема процесу авторизації

Усі сценарії входу починаються з одного запиту — POST /api/v2/account/login (email і password). Далі шлях залежить від налаштувань облікового запису:

Сценарій	Що надсилаєте	Що отримуєте	Наступна дія
2FA вимкнено	`POST /api/v2/account/login`	`token`	Використовуйте `token` у заголовку `Authorization`
2FA увімкнено, перший вхід	`POST /api/v2/account/login` → `POST /api/v2/account/verify-2fa`	`pre_auth_token` + QR → `token`	Відскануйте QR, потім підтвердіть код
2FA увімкнено, регулярний вхід	`POST /api/v2/account/login` → `POST /api/v2/account/verify-2fa`	`pre_auth_token` → `token`	Введіть поточний код з додатка

інформація

Тимчасовий pre_auth_token дійсний 5 хвилин. Якщо час вичерпано — повторіть логін з початку.

2FA вимкнено (стандартний вхід)

URI: /api/v2/account/login

Запит виконується методом POST з тілом запиту у json форматі.

Детальний опис методу — на сторінці /account/login/.

Параметри запиту

Ім'я	Тип	Обов'язковий	Опис
email	string	Так	Електронна пошта співробітника (логін для авторизації в Skarb Cloud)
password	string	Так	Пароль співробітника для авторизації в Skarb Cloud

Приклад запиту

Запит: /api/v2/account/login
{
    "email": "[email protected]",
    "password": "your_password"
}

Приклад успішної відповіді

200 OK

Успішна відповідь: /api/v2/account/login
{
    "data": {
        "token": "abc123...",
        "url": "https://..."
    }
}

інформація

Використовуйте отриманий token у заголовку Authorization для всіх наступних запитів до API:

Authorization = "Bearer abc123..."

2FA увімкнено

Перший вхід (додаток автентифікації ще не налаштовано)

Якщо двофакторну автентифікацію увімкнено, але додаток-автентифікатор ще не налаштовано (або QR-код був отриманий раніше, але так і не був успішно підтверджений), перший вхід повертає дані для генерації QR-коду.

інформація

Якщо ви отримали QR-код під час попередньої спроби входу, але не відсканували його, система згенерує новий QR-код при наступній спробі. Просто відскануйте новий код і завершіть перевірку.

Логін

URI: /api/v2/account/login

Запит виконується методом POST з тілом запиту у json форматі.

Параметри запиту

Ім'я	Тип	Обов'язковий	Опис
email	string	Так	Електронна пошта співробітника (логін для авторизації в Skarb Cloud)
password	string	Так	Пароль співробітника для авторизації в Skarb Cloud

Приклад запиту

Запит: /api/v2/account/login
{
    "email": "[email protected]",
    "password": "your_password"
}

Приклад відповіді

200 OK

Відповідь: /api/v2/account/login
{
    "data": {
        "pre_auth_token": "xyz789...",
        "qr_code_url": "otpauth://totp/SkarbCloud:[email protected]?secret=BASE32SECRET&issuer=SkarbCloud",
        "qr_code_base64": "iVBORw0KGgoAAA..."
    }
}

Налаштування додатка-автентифікатора

Відкрийте Google Authenticator, Authy або будь-який інший сумісний із TOTP додаток.
Натисніть + → Сканувати QR-код і відскануйте зображення, отримане з qr_code_base64. Альтернативно можна використати ручне введення секретного ключа в додатку.
Додаток почне генерувати 6-значні коди, які оновлюються кожні 30 секунд.

Підтвердження коду

URI: /api/v2/account/verify-2fa

Запит виконується методом POST з тілом запиту у json форматі.

Параметри запиту

Ім'я	Тип	Обов'язковий	Опис
pre_auth_token	string	Так	Тимчасовий токен попередньої авторизації, отриманий після успішного логіну
code	string	Так	6-значний OTP-код з додатка-автентифікатора

Приклад запиту

Запит: /api/v2/account/verify-2fa
{
    "pre_auth_token": "xyz789...",
    "code": "123456"
}

Приклад успішної відповіді

200 OK

Успішна відповідь: /api/v2/account/verify-2fa
{
    "data": {
        "token": "abc123...",
        "url": "https://..."
    }
}

інформація

Використовуйте отриманий token у заголовку Authorization для всіх наступних запитів до API:

Authorization = "Bearer abc123..."

попередження

Тимчасовий pre_auth_token дійсний лише 5 хвилин. Якщо час вичерпано, повторіть Крок 1

Регулярний вхід (автентифікатор уже налаштовано)

Логін

URI: /api/v2/account/login

Запит виконується методом POST з тілом запиту у json форматі.

Параметри запиту

Ім'я	Тип	Обов'язковий	Опис
email	string	Так	Електронна пошта співробітника (логін для авторизації в Skarb Cloud)
password	string	Так	Пароль співробітника для авторизації в Skarb Cloud

Приклад запиту

Запит: /api/v2/account/login
{
    "email": "[email protected]",
    "password": "your_password"
}

Приклад відповіді

200 OK

Відповідь: /api/v2/account/login
{
    "data": {
        "pre_auth_token": "xyz789..."
    }
}

Введення коду з додатка

Відкрийте ваш додаток-автентифікатор та знайдіть поточний 6-значний код для SkarbCloud.

URI: /api/v2/account/verify-2fa

Запит виконується методом POST з тілом запиту у json форматі.

Параметри запиту

Ім'я	Тип	Обов'язковий	Опис
pre_auth_token	string	Так	Тимчасовий токен попередньої авторизації, отриманий після успішного логіну
code	string	Так	6-значний OTP-код з додатка-автентифікатора

Приклад запиту

Запит: /api/v2/account/verify-2fa
{
    "pre_auth_token": "xyz789...",
    "code": "123456"
}

Приклад успішної відповіді

200 OK

Успішна відповідь: /api/v2/account/verify-2fa
{
    "data": {
        "token": "abc123...",
        "url": "https://..."
    }
}

попередження

Тимчасовий pre_auth_token дійсний лише 5 хвилин. Якщо час вичерпано, повторіть Крок 1

Обробка помилок

HTTP статус	Текст помилки	Причина виникнення
422	Токен недійсний або прострочений	pre_auth_token прострочений або некоректний
422	Невірний код підтвердження	Введено неправильний OTP-код з додатка
422	Код підтвердження має містити 6 цифр	Некоректний формат OTP-коду (не 6 знаків)
422	Перевищено кількість спроб підтвердження 2FA	Забагато невдалих спроб введення коду для одного pre_auth_token
422	Помилка конфігурації 2FA	Помилка налаштування 2FA на стороні сервера
422	email: Користувач не знайдений в базі	Користувача з таким Email не існує
422	password: Невірний пароль	Вказано неправильний пароль
403	Помилка авторизації некоректний заголовок API-Key	Відсутній або неправильний заголовок `API-Key`

Authorization/Two-Factor Authentication​

Схема процесу авторизації​

2FA вимкнено (стандартний вхід)​

Параметри запиту​

Приклад запиту​

Приклад успішної відповіді​

2FA увімкнено​

Перший вхід (додаток автентифікації ще не налаштовано)​

Логін​

Параметри запиту​

Приклад запиту​

Приклад відповіді​

Налаштування додатка-автентифікатора​

Підтвердження коду​

Параметри запиту​

Приклад запиту​

Приклад успішної відповіді​

Регулярний вхід (автентифікатор уже налаштовано)​

Логін​

Параметри запиту​

Приклад запиту​

Приклад відповіді​

Введення коду з додатка​

Параметри запиту​

Приклад запиту​

Приклад успішної відповіді​

Обробка помилок​

Authorization/Two-Factor Authentication

Схема процесу авторизації

2FA вимкнено (стандартний вхід)

Параметри запиту

Приклад запиту

Приклад успішної відповіді

2FA увімкнено

Перший вхід (додаток автентифікації ще не налаштовано)

Логін

Параметри запиту

Приклад запиту

Приклад відповіді

Налаштування додатка-автентифікатора

Підтвердження коду

Параметри запиту

Приклад запиту

Приклад успішної відповіді

Регулярний вхід (автентифікатор уже налаштовано)

Логін

Параметри запиту

Приклад запиту

Приклад відповіді

Введення коду з додатка

Параметри запиту

Приклад запиту

Приклад успішної відповіді

Обробка помилок