Lewati ke konten
Hashee Docs

Autentikasi

Đăng Ký (4 Bước)

Đăng ký yêu cầu xác minh email, mật khẩu và tên hiển thị:

Bước 1: Gửi Mã Xác Minh

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

Bước 2: Đăng Ký

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

Trả về access token và refresh token (dưới dạng HttpOnly cookie).

Bước 3: Client Tạo Khóa

Sau đăng ký, client:

  1. Tạo cặp khóa X25519
  2. Dẫn xuất khóa mã hóa: Argon2id(protection_password, random_salt)
  3. Mã hóa khóa riêng: AES-GCM(derived_key, private_key)

Bước 4: Tải Bản Sao Khóa

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

Đăng Nhập

Hỗ trợ ba phương thức đăng nhập:

Đăng Nhập Bằng Mật Khẩu

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

Khóa tài khoản: Sau 5 lần đăng nhập thất bại, tài khoản bị khóa 15 phút. Trả về 423 ACCOUNT_LOCKED với retry_after tính bằng giây.

Đăng Nhập Bằng Mã Xác Minh

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


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

Đăng Nhập Passkey

Passkey thay thế mật khẩu tài khoản trong bước xác thực. Mật khẩu bảo vệ (cho giải mã khóa) vẫn cần trên thiết bị mới.

Terminal window
POST /auth/passkey/begin     # Trả về challenge (endpoint công khai)
POST /auth/passkey/complete   # Xác minh chữ ký, phát hành token (endpoint công khai)

Đăng nhập Passkey sử dụng WebAuthn Conditional UI — không có nút rõ ràng trên màn hình đăng nhập. Prompt Passkey hệ thống tự động xuất hiện trên thiết bị hỗ trợ.

Làm Mới Token

Access token hết hạn sau 5 phút. Dùng refresh token để lấy cặp mới:

Terminal window
POST /auth/refresh

Refresh token được lưu dưới dạng HttpOnly cookie với các thuộc tính:

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

Đặt Lại Mật Khẩu

Đặt lại mật khẩu tài khoản không ảnh hưởng khóa mã hóa:

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" }

Xác Thực Agent

Agent sử dụng token lâu dài thay vì JWT:

Authorization: Bearer hsk_your-agent-token

Định dạng token là hsk_ + 40 ký tự base62. Máy chủ lưu hash bcrypt.

Xác Thực WebSocket

Với kết nối WebSocket, token được gửi trong frame đầu tiên (không bao giờ trong URL):

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

Máy chủ phản hồi { "type": "auth.ok" } hoặc { "type": "auth.error", "reason": "..." }.

Tái Tạo Token

Terminal window
POST /agents/:id/token/regenerate
{ "emergency": false }
Chế độToken cũKhóa công khai cũ
Bình thường (emergency: false)Hợp lệ 7 ngàyHợp lệ 7 ngày
Khẩn cấp (emergency: true)Thu hồi ngayThu hồi ngay

Bước Tiếp Theo