Перейти до основного вмісту

Авторизація​

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

  • Без 2FA (стандартний вхід): процес авторизації виконується в один крок. Ви надсилаєте запит із логіном та паролем і одразу отримуєте постійний токен доступу для подальшої роботи (детальніше див. /account/login/).
порада

Раніше (до 20.05.2026): вхід без 2FA був доступний для облікових записів, у яких двофакторну автентифікацію не було увімкнено.

Тепер (з 20.05.2026): двофакторна автентифікація обов'язкова для всіх користувачів.

  • 2FA увімкнено (безпечний вхід): система використовує двоступеневий процес входу. Після перевірки логіна та пароля /account/login/ повертає pre_auth_token, короткоживучий token та expires_in. Для завершення входу підтвердіть 2FA одним із способів:
інформація

Двофакторна аутентифікація (TOTP) підтримує будь-який додаток: Microsoft Authenticator, Google Authenticator, Authy тощо.

Для найкращої сумісності та безпеки використовуйте Microsoft Authenticator

Життєвий цикл токена​

Після успішного /account/login/ API повертає token із коротким терміном дії (expires_in, зазвичай 300 секунд — 5 хвилин). Цей токен дійсний на етапі очікування підтвердження 2FA.

Після успішного підтвердження 2FA (/account/verify-2fa/ або /api/v2/account/verify-2fa-by-sign/) той самий token продовжується — у відповіді приходить оновлене значення expires_in. Зберігайте token і expires_in у клієнті та використовуйте token у заголовку Authorization: Bearer ... для подальших запитів до API.

Поле expires_in повертається у відповідях методів авторизації та вказує, скільки секунд залишилось до закінчення дії поточного токена.

Відновлення після прострочення токена​

Якщо token прострочився під час роботи з API, сервер повертає помилку авторизації разом із полем url — посиланням для повторної авторизації в eHealth. Клієнт має перенаправити користувача за цим посиланням, пройти авторизацію в eHealth і продовжити роботу без повного перезапуску сценарію входу (логін + 2FA), якщо recovery-сценарій доступний для вашого облікового запису.

Детальніше про формат помилки — у розділі Формат запитів до API.

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

Якщо облікова система не реалізує повний цикл API-2FA (login → verify-2fa), можна відкрити сторінку входу додатка у віджеті / браузері.

Посилання повертається в полі eHealthOAuthUrl після запиту до захищеного методу з простроченим токеном.

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

У цьому сценарії eHealthOAuthUrl не стосується eHealth — це адреса сторінки входу в додаток.

Покрокова інструкція: Авторизація через віджет.

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

  1. Виконайте запит POST /account/login/, передавши email та password.
  2. Подальший шлях залежить від того, чи налаштовано додаток-аутентифікатор для облікового запису:

  • Перший вхід (додаток-аутентифікатор ще НЕ налаштовано) (детальніше див. /account/verify-2fa):

    1. Отримайте у відповіді token, expires_in, pre_auth_token та дані QR-коду.

    2. Відкрийте Google Authenticator, Microsoft Authenticator, Authy або інший TOTP-додаток.

    3. Натисніть + → Сканувати QR-код та відскануйте зображення з отриманого qr_code_base64 (або введіть ключ вручну).

    4. Знайдіть згенерований 6-значний код для SkarbCloud у додатку.

    5. Надішліть запит POST /account/verify-2fa/, передавши pre_auth_token та цей 6-значний код у параметрі code.

    6. Отримайте продовжений token із оновленим expires_in. Вхід завершено успішно.

  • Регулярний вхід (додаток-аутентифікатор ВЖЕ налаштовано) (детальніше див. /account/verify-2fa або /account/verify-2fa-by-sign):

    1. Отримайте у відповіді token, expires_in та pre_auth_token.

    2. Підтвердіть 2FA одним із способів:

      • TOTP — знайдіть 6-значний код у додатку-автентифікаторі та надішліть POST /account/verify-2fa/ з pre_auth_token і code;
      • КЕП — підпишіть дані кваліфікованим електронним підписом і надішліть POST /api/v2/account/verify-2fa-by-sign/ з pre_auth_token і signed_string.

    3. Отримайте продовжений token із оновленим expires_in. Вхід завершено успішно.

інформація

Короткоживучий token і pre_auth_token дійсні 5 хвилин (expires_in: 300). Якщо час вичерпано — повторіть логін з початку.