Аутентификация
У Runne Pass две независимые поверхности аутентификации:
| Поверхность | Учётные данные | Транспорт | Кем используется |
|---|---|---|---|
| Кабинет клиента | JWT в HttpOnly-cookie | Cookie runne_session | Веб-кабинет, браузер |
| Программный API | API-ключ rn_live_… | Authorization: Bearer или x-api-key | Серверы, скрипты, SDK |
Они не взаимозаменяемы: cookie-сессии авторизуют маршруты кабинета, API-ключи — внешнюю поверхность chat/balance.
Cookie-сессия (кабинет)
Вход и регистрация
POST /v1/auth/register—{email, password, name}, создаёт клиента, затем автоматически выполняет вход и устанавливает cookie.POST /v1/auth/login—{email, password}, устанавливает cookie и возвращает{expires_at}.POST /v1/auth/logout— отзывает сессию на стороне сервера и очищает cookie.GET /v1/auth/me— возвращает профиль текущего клиента.
Атрибуты cookie сессии
| Атрибут | Значение |
|---|---|
| Имя | runne_session |
HttpOnly | да |
SameSite | Lax |
Secure | только в production (NODE_ENV=production) |
Max-Age | 24 часа (совпадает со сроком жизни JWT) |
Path | / |
JWT несёт customerId, email, isAdmin и уникальный jti.
Отзыв на стороне сервера
Logout помещает jti сессии в denylist Redis с ключом bl:sess:{jti} и TTL, равным оставшемуся сроку жизни токена. Каждый аутентифицированный запрос перепроверяет denylist, поэтому вышедшая сессия перестаёт работать сразу, хотя сам JWT ещё криптографически валиден.
API-ключи (программные клиенты)
Формат
rn_live_<keyId>_<secret>keyId— 12 символов, base64url, производная от 9 случайных байт.secret— 32 случайных байта, base64url.- Префикс
rn_live_помечает ключ как боевой (не тестовый).
Передача ключа
Два эквивалентных способа:
# Заголовок Authorization (предпочтительно)
curl -H 'Authorization: Bearer rn_live_…' …
# Заголовок x-api-key
curl -H 'x-api-key: rn_live_…' …Проверка
Сервер разбирает ключ, находит строку по keyId и сверяет secret через HMAC-SHA256 с хранимым хешем. Хранится только хеш — исходный секрет никогда не сохраняется.
Ротация двух секретов
Проверка ключей поддерживает два серверных секрета:
API_KEY_SERVER_SECRET— текущий секрет.API_KEY_SERVER_SECRET_PREV— предыдущий секрет, для плавной ротации.
В окно ротации ключи, захэшированные под предыдущим секретом, всё ещё проходят проверку, поэтому можно ротировать серверный секрет, не инвалидируя живые ключи. Сравнение выполняется за постоянное время.
Скоупы
API-ключи несут список scopes. Полная матрица скоупов — в разделе API-ключи.
Raw-ключ показывается один раз
При создании сервер возвращает raw_key, затем отбрасывает его. Пути восстановления нет — см. API-ключи.