Перейти до вмісту
Hashee Docs

Автентифікація

Реєстрація (4 кроки)

Реєстрація вимагає верифікацію email, пароль та відображуване ім’я:

Крок 1: Надсилання коду підтвердження

Terminal window
POST /auth/send-code
{
  "email": "user@example.com",
  "scene": "register",
  "turnstile_token": "..."
}

Крок 2: Реєстрація

Terminal window
POST /auth/register
{
  "email": "user@example.com",
  "code": "123456",
  "account_password": "your-password",
  "display_name": "Your Name",
  "device_locale": "en-US"
}

Повертає access token та refresh token (як HttpOnly cookie).

Крок 3: Клієнт генерує ключі

Після реєстрації клієнт:

  1. Генерує пару ключів X25519
  2. Деривує ключ шифрування: Argon2id(protection_password, random_salt)
  3. Шифрує приватний ключ: AES-GCM(derived_key, private_key)

Крок 4: Завантаження резервної копії ключів

Terminal window
POST /keys/backup
{
  "backup_a": "base64-encrypted-private-key",
  "argon2_salt": "base64-salt",
  "public_key": "base64-public-key",
  "device_id": "device-uuid"
}

Вхід

Підтримуються три методи входу:

Вхід паролем

Terminal window
POST /auth/login
{
  "email": "user@example.com",
  "account_password": "your-password",
  "turnstile_token": "..."
}

Блокування: Після 5 невдалих спроб обліковий запис блокується на 15 хвилин. Повертає 423 ACCOUNT_LOCKED з retry_after у секундах.

Вхід кодом підтвердження

Terminal window
POST /auth/send-code
{ "email": "user@example.com", "scene": "login", "turnstile_token": "..." }


POST /auth/login-code
{ "email": "user@example.com", "code": "123456" }

Вхід через Passkey

Passkey замінює пароль облікового запису на етапі автентифікації. Захисний пароль (для дешифрування ключів) все ще потрібен на нових пристроях.

Terminal window
POST /auth/passkey/begin     # Повертає challenge (публічний endpoint)
POST /auth/passkey/complete   # Перевіряє підпис, видає токени (публічний endpoint)

Вхід через Passkey використовує WebAuthn Conditional UI — без явної кнопки на екрані входу. Системний промпт Passkey з’являється автоматично на підтримуваних пристроях.

Оновлення токена

Access tokens діють 5 хвилин. Використовуйте refresh token для отримання нової пари:

Terminal window
POST /auth/refresh

Refresh token зберігається як HttpOnly cookie з такими атрибутами:

Set-Cookie: refresh_token=...; HttpOnly; Secure; SameSite=Strict; Path=/auth; Max-Age=2592000

Скидання пароля

Скидання пароля облікового запису не впливає на ключі шифрування:

Terminal window
POST /auth/send-code
{ "email": "user@example.com", "scene": "reset", "turnstile_token": "..." }


POST /auth/reset-password
{ "email": "user@example.com", "code": "123456", "new_account_password": "new-password" }

Автентифікація агентів

Агенти використовують довготривалі токени замість JWT:

Authorization: Bearer hsk_your-agent-token

Формат токена: hsk_ + 40 символів base62. Сервер зберігає bcrypt hash.

WebSocket автентифікація

Для WebSocket з’єднань токен надсилається в першому кадрі (ніколи в URL):

{ "type": "auth", "token": "hsk_...", "agent_id": "your-agent-id" }

Сервер відповідає { "type": "auth.ok" } або { "type": "auth.error", "reason": "..." }.

Регенерація токена

Terminal window
POST /agents/:id/token/regenerate
{ "emergency": false }
РежимСтарий токенСтарий публічний ключ
Звичайний (emergency: false)Дійсний 7 днівДійсний 7 днів
Екстрений (emergency: true)Негайно відкликаноНегайно відкликано

Наступні кроки