Аутентификация детально
Технические детали аутентификации V3 Custody — вход по magic-link, сессия better-auth, Bearer и cookie, ошибки и модель доступа.
Эта страница углубляет вводную Аутентификацию: здесь — вход по magic-link, жизненный цикл сессии, механика Bearer и cookie и граничные случаи. Оба способа аутентификации построены на сессии better-auth: Bearer-токен для сервисов и мобильных, httpOnly-cookie для веба.
Вход по magic-link
Вход выполняется по magic-link, а не по паролю:
POST /api/v1/auth/magic-link— отправляет magic-link на email (через Cloudflare Email binding). Войти могут только существующие пользователи и приглашённые (с активным приглашением) — регистрация без приглашения заблокирована hook'ом better-auth. После клика по ссылке пользователь редиректится на фронтенд (FRONTEND_URL).
curl -X POST "[BASE_URL]/api/v1/auth/magic-link" \
-H "Content-Type: application/json" \
-d '{ "email": "trader@acme.com" }'
await fetch("[BASE_URL]/api/v1/auth/magic-link", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ email: "trader@acme.com" }),
});
import requests
requests.post(
"[BASE_URL]/api/v1/auth/magic-link",
json={"email": "trader@acme.com"},
)
Точная схема тела запроса — в Справочнике API на странице magic-link. Поля в примере приведены для иллюстрации.
Сессия better-auth
После входа создаётся сессия better-auth. Веб получает httpOnly-cookie, а сервисы и мобильные используют токен сессии как Bearer.
- Срок действия сессии — [TODO: указать время жизни сессии/токена].
- Обновление и ротация — [TODO: описать механизм refresh/ротации токена, если он есть].
Bearer — для сервисов и мобильных
Передайте токен сессии в заголовке:
Authorization: Bearer <токен>
[TODO: описать, как серверная интеграция получает токен доступа для Bearer — механизм выдачи пока уточняется. Найти по метке TODO.]
Cookie — для веба
При входе через веб-консоль better-auth выставляет httpOnly-cookie с сессией. Браузер отправляет её автоматически, из JavaScript она недоступна по замыслу.
- Имя cookie — [TODO: уточнить имя session-cookie].
- Защита от CSRF — [TODO: описать механизм CSRF для cookie-запросов].
Для интеграций «сервер↔сервер» используйте Bearer, а не cookie.
Ошибки аутентификации
Без валидного токена или сессии вернётся 401:
{
"error": "Unauthorized",
"message": "Authentication required. Please provide a valid API token",
"code": 401
}
Аутентифицированный, но недостаточно авторизованный запрос вернёт 403 — доступ определяется членством в группах (default-deny; без allow-политик действия запрещены).
Модель доступа
Аутентификация отвечает «кто вы», доступ — «что вам можно». В V3 Custody права определяются членством в группах политик, отдельных «скоупов» у токена нет. Видимость по умолчанию изолирована: участник видит своё, администратор — весь Vault; расширяется через visibility-grants. Подробнее — на странице Аутентификация и в гайде Пригласить команду.
Лимиты запросов
[TODO: описать rate limits на аутентификацию и API, если они есть.]