跳到內容
Hashee Docs

驗證

註冊（4 步驟）

註冊需要電子郵件驗證、密碼和顯示名稱：

步驟 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     # 返回挑戰（公開端點）
POST /auth/passkey/complete   # 驗證簽章，發放 Token（公開端點）

Passkey 登入使用 WebAuthn Conditional UI——登入畫面上沒有明確的按鈕。系統的 Passkey 提示會在支援的裝置上自動出現。

Token 重新整理

Access Token 在 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" }

Agent 驗證

Agent 使用長期 Token 而非 JWT：

Authorization: Bearer hsk_your-agent-token

Token 格式為 hsk_ + 40 個 base62 字元。伺服器儲存 bcrypt 雜湊。

WebSocket 驗證

對於 WebSocket 連接，Token 在首幀中傳送（永遠不放在 URL 中）：

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

伺服器回應 { "type": "auth.ok" } 或 { "type": "auth.error", "reason": "..." }。

Token 重新產生

Terminal window
POST /agents/:id/token/regenerate
{ "emergency": false }
模式舊 Token舊公鑰
一般（emergency: false）有效 7 天有效 7 天
緊急（emergency: true）立即撤銷立即撤銷

下一步