Аутентификация¶

Публичный API использует Bearer-токены. Каждый запрос должен содержать заголовок:

Authorization: Bearer tn_live_<prefix>_<secret>

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

tn_live_aB3kP9qX_h7nZk2Xc1Yv4uG8wRsT5jLpM6oNqEi
└─env─┘ └─prefix─┘ └────────── секрет ──────────┘

tn_live_ — фиксированный префикс окружения (продакшен).
prefix — 8 alphanumeric-символов, публичный идентификатор ключа. По нему мы быстро находим запись в БД. Не считается секретом, но и публиковать его специально не нужно.
secret — секретная часть (≥32 символа). В БД хранится только её bcrypt-хэш; восстановить плейн-текст невозможно.

Создание ключа¶

Дашборд → Keys → New key → задайте метку. Плейн-текст показывается один раз на странице создания.

Сохраните токен сразу

После закрытия модального окна вы больше не сможете увидеть полный токен. Если потеряли — создайте новый и удалите старый (см. ниже).

Хранение¶

Никогда не коммитьте ключи в git.
Используйте переменные окружения или менеджер секретов (1Password, HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager).
В CI — секреты через GitHub Actions Secrets / GitLab CI Variables.
На клиенте (мобильное приложение, браузер) — не используйте ключи напрямую. Запросы к TrueNum API должны идти через ваш бэкенд, иначе ключ можно вытащить из бинаря/JS.

Отзыв ключа (revoke)¶

Дашборд → Keys → нажать Revoke напротив нужного ключа. Отзыв необратим и срабатывает мгновенно: со следующего же запроса TrueNum API будет отвечать 401 Unauthorized.

Сценарий «утечка ключа в публичный репозиторий»:

Сразу отзовите скомпрометированный ключ.
Создайте новый и обновите его в продакшене.
Просмотрите GET /api/dashboard/verifications (в дашборде) на предмет аномальной активности от старого ключа за последние сутки.
Если нашли мошеннический трафик — напишите в саппорт TrueNum.

Ротация¶

Рекомендуется ротировать ключи каждые 90 дней или при смене сотрудника с доступом. Безпростойная схема:

Создайте новый ключ.
Раскатите его в продакшен (canary → 100 %).
Через сутки убедитесь, что у старого ключа last_used_at не обновляется → отзовите старый.

Ошибки аутентификации¶

Код	Когда
`401 Unauthorized` — `{"detail": "Authentication credentials were not provided."}`	Отсутствует заголовок `Authorization`
`401 Unauthorized` — `{"detail": "Invalid token."}`	Неверный формат, неизвестный prefix или несовпавший секрет
`401 Unauthorized` — `{"detail": "Token revoked."}`	Ключ отозван через дашборд
`403 Forbidden` — `{"detail": "API key required."}`	Запрос прошёл другой аутентификации (например, сессия дашборда) — попадание не на тот эндпоинт

Подробнее — Ошибки.

Логи использования¶

В дашборде на странице Keys для каждого ключа показывается:

created_at — когда создан.
last_used_at — момент последнего успешного запроса (обновляется асинхронно через очередь, лаг до нескольких секунд).
is_active — отозван ли.

Если last_used_at несвежий — ключ можно безопасно ротировать.