Авторизація через віджет

Цей сценарій потрібен, якщо облікова система не має власного інтерфейсу для введення коду двофакторної автентифікації, а відкриває сторінку входу СКАРБ Cloud у віджеті або браузері.

Посилання на сторінку входу повертається в полі eHealthOAuthUrl, коли одночасно виконано всі умови:

Умова	Деталі
Увімкнено API-2FA	Для облікового запису активна двофакторна автентифікація через API
Отримано короткоживучий токен	Після /account/login/ у відповіді є token з expires_in: 2
2FA через API не підтверджено	Не викликано /account/verify-2fa/ або /account/verify-2fa-by-sign/
Токен прострочений	Виконано запит до будь-якого захищеного методу API з цим токеном

Як це працює

1. Виконайте /account/login/ — у відповіді прийде короткоживучий token (expires_in: 2).
2. Не підтверджуйте 2FA через API (не викликайте /account/verify-2fa/ або /account/verify-2fa-by-sign/).
3. Зачекайте більше 2 секунд, поки токен стане недійсним.
4. Зверніться до будь-якого захищеного методу API з цим токеном.
5. У відповіді HTTP 403 візьміть eHealthOAuthUrl і відкрийте його у віджеті або браузері — користувач завершить вхід у СКАРБ Cloud.

Увага!

Поле eHealthOAuthUrl тут не веде в eHealth. Це адреса сторінки входу в додаток (наприклад, https://<хост-додатка>/account).

Альтернатива

Якщо потрібна повна інтеграція 2FA через API — використовуйте цикл: /account/login/ → /account/verify-2fa/ або /account/verify-2fa-by-sign/.

Інструкція: отримання посилання для авторизації

Крок 1. Виконайте вхід

Надішліть POST-запит для авторизації користувача

POST /api/v2/account/login
API-Key: <ваш API-ключ>
Content-Type: application/json

Тіло запиту

{
  "email": "[email protected]",
  "password": "ваш_пароль"
}

Якщо для облікового запису увімкнено API-2FA, у відповіді прийде токен із коротким терміном дії 2 секунди та повідомлення про необхідність підтвердити другий фактор:

{
  "data": {
    "pre_auth_token": "xyz789...",
    "token": "abc123...",
    "expires_in": 2,
    "message": "Потрібне підтвердження другого фактора: ..."
  }
}

Крок 2. Дочекайтеся закінчення терміну дії токена

1. Не викликайте метод підтвердження другого фактора (verify-2fa).

2. Зачекайте понад 2 секунди.

3. Отриманий токен (abc123...) стане недійсним.

Крок 3. Виконайте запит з простроченим токеном

Зверніться до будь-якого захищеного методу API, передавши прострочений токен у заголовку Authorization:

GET /api/v2/account/me
API-Key: <ваш API-ключ>
Authorization: Bearer abc123...

Система поверне HTTP 403 з повідомленням про завершення терміну дії токена та посиланням на сторінку авторизації.

Параметри відповіді

Ім'я	Тип	Опис
errors	object	Дані про помилку авторизації
errors.message	string	Повідомлення про помилку авторизації
errors.eHealth	string	Повідомлення про помилку авторизації
errors.eHealthOAuthUrl	string	Адреса сторінки входу в додаток. Перейдіть за цим URL у браузері або через віджет, щоб повторно пройти авторизацію через інтерфейс

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

403 Forbidden

Прострочений токен: посилання на сторінку входу

{
  "errors": {
    "eHealth": "Закінчився термін дії токену",
    "eHealthOAuthUrl": "https://<хост-додатка>/account",
    "message": "Закінчився термін дії токену"
  }
}