Перейти к содержанию

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

Публичный 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.

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

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

Ротация

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

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

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

Все ответы — в формате {"detail": "<сообщение>"}. Сообщения сервиса — на русском (язык API — ru).

Код detail Когда
401 Учётные данные не были предоставлены. Нет заголовка Authorization (DRF-сообщение, локализовано)
401 Некорректный заголовок Authorization Заголовок есть, но не вида Bearer <token> (не два токена)
401 Токен содержит недопустимые символы Токен содержит не-ASCII символы
401 Некорректный формат API-ключа Токен не разбирается как tn_live_<prefix>_<secret>
401 Недействительный API-ключ Неизвестный prefix или несовпавший секрет
401 API-ключ был отозван Ключ отозван (revoked) через дашборд
403 Требуется API-ключ. Запрос прошёл другую аутентификацию (не Bearer API-ключ)

При 401 в ответе есть заголовок WWW-Authenticate: Bearer.

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

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

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

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

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