Ga naar inhoud
Hashee Docs

Authenticatie

Registratie (4 stappen)

Registratie vereist e-mailverificatie, een wachtwoord en een weergavenaam:

Stap 1: Verificatiecode versturen

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

Stap 2: Registreren

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

Retourneert een access-token en refresh-token (als HttpOnly-cookie).

Stap 3: Client genereert sleutels

Na registratie doet de client het volgende:

  1. Genereert een X25519-sleutelpaar
  2. Leidt een versleutelingssleutel af: Argon2id(protection_password, random_salt)
  3. Versleutelt de privesleutel: AES-GCM(derived_key, private_key)

Stap 4: Sleutelback-up uploaden

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

Login

Er worden drie loginmethoden ondersteund:

Wachtwoord-login

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

Vergrendeling: Na 5 mislukte pogingen wordt het account 15 minuten vergrendeld. Retourneert 423 ACCOUNT_LOCKED met retry_after in seconden.

Verificatiecode-login

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-login

Passkey vervangt het accountwachtwoord in de authenticatiestap. Het beschermingswachtwoord (voor sleutelontsleuteling) is nog steeds nodig op nieuwe apparaten.

Terminal window
POST /auth/passkey/begin     # Returns challenge (public endpoint)
POST /auth/passkey/complete   # Verifies signature, issues tokens (public endpoint)

Passkey-login gebruikt WebAuthn Conditional UI — geen expliciete knop op het loginscherm. De systeem-Passkey-prompt verschijnt automatisch op ondersteunde apparaten.

Token vernieuwen

Access-tokens verlopen na 5 minuten. Gebruik het refresh-token om een nieuw paar te krijgen:

Terminal window
POST /auth/refresh

Het refresh-token wordt opgeslagen als een HttpOnly-cookie met deze attributen:

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

Wachtwoord herstellen

Herstellen van het accountwachtwoord heeft geen invloed op versleutelingssleutels:

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-authenticatie

Agents gebruiken langdurige tokens in plaats van JWT:

Authorization: Bearer hsk_your-agent-token

Het tokenformaat is hsk_ + 40 base62-tekens. De server slaat de bcrypt-hash op.

WebSocket-authenticatie

Voor WebSocket-verbindingen wordt het token in het eerste frame verstuurd (nooit in de URL):

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

De server reageert met { "type": "auth.ok" } of { "type": "auth.error", "reason": "..." }.

Token-regeneratie

Terminal window
POST /agents/:id/token/regenerate
{ "emergency": false }
ModusOud tokenOude publieke sleutel
Normaal (emergency: false)7 dagen geldig7 dagen geldig
Noodgeval (emergency: true)Onmiddellijk ingetrokkenOnmiddellijk ingetrokken

Volgende stappen