Authentication

Finance OS API поддерживает два механизма аутентификации. Оба используют стандартный заголовок Authorization: Bearer ... — клиенту не нужно их различать, middleware на сервере определит формат сам.

Сравнение

API Keys (для серверов)

Похоже на то, как работают Stripe / Plaid / Twilio: у каждого пользователя две пары ключей — для Live (production) и Sandbox (test). Каждая пара состоит из публичного и секретного ключа.

Как сгенерировать

1. Войти в fin-os.io
2. Сайдбар → Настройки → API ключи
3. Переключить тоггл MAIN / SANDBOX в нужное окружение
4. Нажать «Сгенерировать Live ключи» (или Sandbox)
5. В модальном окне скопировать sk_live_… / sk_test_… — он показывается только один раз

Формат ключей

Использование

Authorization: Bearer sk_live_abc123...

Это всё. Передавайте на каждом запросе к защищённым endpoints. Никакого логина, никаких рефреш-токенов.

Lifecycle

• Срок жизни: ключ живёт до явной перегенерации. По таймеру не истекает.
• Регенерация: кнопка «Перегенерировать» в кабинете создаёт новую пару и инвалидирует старую немедленно. Все клиенты со старым ключом получат 401, пока не обновят.
• Отзыв без выпуска нового: отдельной операции нет — перегенерируйте, чтобы убить старый ключ. Если нужно временно «выключить» интеграцию — отзовите доступ на стороне клиента.
• Last-used трекинг: на странице ключей видно last_used_at и last_used_ip — полезно для аудита.

Mobile Sessions (для приложений)

Под капотом — Laravel Sanctum. Каждый login через POST /api/mobile/login создаёт новую запись в personal_access_tokens и возвращает токен-сессию клиенту.

Flow

POST /api/mobile/login
Content-Type: application/json

{
  "email": "you@example.com",
  "password": "...",
  "device_name": "iPhone 15"
}

# → 200 OK
{
  "data": {
    "token": "123|aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890aBcDeFgH",
    ...
  }
}

Формат токена

Возвращается строкой вида 123|aBcDeFgH…:

• 123 — ID записи в personal_access_tokens
• | — разделитель
• aBcDeFgH… (40 символов) — собственно секрет

Передавайте всю строку целиком: Authorization: Bearer 123|aBcDeFgH...

Двухфакторная аутентификация

Если на аккаунте включён 2FA, первый POST /api/mobile/login вернёт 422 с телом:

{
  "message": "Two-factor authentication required.",
  "error_code": "TWO_FACTOR_REQUIRED",
  "requires_2fa": true
}

Запросите код у пользователя и повторите login с добавленным two_factor_code (или recovery_code).

Управление сессиями

Как сервер различает форматы

Один и тот же endpoint принимает оба типа Bearer'а — для клиента это прозрачно:

# Вариант A: API key
Authorization: Bearer sk_live_aBcDeFgH...

# Вариант B: Sanctum session
Authorization: Bearer 123|aBcDeFgH...

Под капотом middleware-стек:

1. AuthenticateApiKey смотрит на bearer. Если совпадает с regex /^sk_(live|test)_[A-Za-z0-9]+$/ — ищет в api_keys.secret_hash, и при совпадении ставит пользователя в Sanctum-guard.
2. auth:sanctum отрабатывает дальше. Если юзер уже выставлен предыдущим middleware — пропускает. Если нет — пытается резолвить bearer как Sanctum-токен (формат id|secret).

Поэтому никакой разницы в коде клиента — пишите любой формат, всё работает.

Scopes (v1.1)

В v1 у всех ключей — полный доступ к ресурсам владельца (abilities = ['*'] в Sanctum). В v1.1 планируется:

• API Keys scopes: read-only, trading-only, withdrawal, business
• Public key scope: pk_live_… получит read-only-доступ к публичным эндпоинтам (тикеры, статус сети) — безопасно встраивать в frontend
• Sandbox-режим: сейчас sk_test_… работает как обычный ключ; в v1.1 sandbox начнёт реально подменять транзакции на mock'и

Ошибки