API-referentie

Basis: https://api.rempar.org/v1. Overal JSON. Geslaagde antwoorden zijn omhuld in {"data": ...}, fouten in {"error": {"code": "...", "message": "..."}}. Authenticatie met een Bearer-token dat eigen is aan elk apparaat.

De API is zero-knowledge: zij ontvangt nooit een wachtwoord of inhoud in klare tekst. Clients van derden zijn welkom zolang zij het protocol v1 respecteren.

Gezondheid

GET /v1/health
→ { "data": { "status": "ok", "release": "1.1.0" } }

Authenticatie

Methode Route Body Antwoord
POST /auth/prelogin {email} {kdf, kdf_salt}. Deterministisch vals salt als het e-mailadres onbekend is.
POST /auth/register {email, auth_key, kdf, kdf_salt, device} 201 {status: "verification_sent"}. Een zescijferige code wordt per e-mail verzonden.
POST /auth/verify-email {email, code} {}
POST /auth/login {email, auth_key, device, totp?, code?} {tokens, device_id, vault_key_sealed?}. Fout totp_required (403) als 2FA actief is en de code ontbreekt. Daarna email_code_required (403): een zescijferige code wordt per e-mail verzonden en moet in code worden teruggestuurd om de tokens te krijgen (10 min, 5 pogingen).
POST /auth/refresh {refresh_token} {access_token, refresh_token, ...}. Rotatie; een herhaling trekt het apparaat in.
POST /auth/logout Trekt het huidige apparaat in.
POST /auth/recover {email, recovery_auth, totp?} Bewijs van de noodkit: geeft {vault_key_recovery, recovery_token} (15 min). totp_required als 2FA actief is.
POST /auth/recover/complete {email, recovery_token, auth_key, kdf, kdf_salt, vault_key_sealed, device} Nieuw hoofdwachtwoord: vervangt de authenticatiesleutel en de opnieuw verzegelde kluissleutel, trekt alle andere apparaten in en meldt dit apparaat aan ({tokens, device_id, vault_key_sealed}).

device: {name, platform, client_id} waarbij client_id een door de client gekozen UUID is, stabiel voor dit apparaat.

kdf: {"algo": "argon2id", "m": 65536, "t": 3, "p": 4}. Clients weigeren parameters die zwakker zijn dan m=19456, t=2, p=1.

Account

Methode Route Beschrijving
GET /account E-mail, 2FA-status, kluisrevisie, abonnement {plan, active, until}.
GET /account/subscription Alleen het abonnement.
POST /account/password Vervangt auth_key na een wijziging van het hoofdwachtwoord. De client publiceert eerst de opnieuw verzegelde kluissleutel.
GET /account/devices Actieve apparaten.
DELETE /account/devices/{id} Trekt een apparaat in.
POST /account/totp/setup Genereert een geheim en geeft {secret, otpauth_url} terug.
POST /account/totp/enable {code}: activeert 2FA.
POST /account/totp/disable {code}: schakelt 2FA uit.

Kluis

Methode Route Beschrijving
PUT /vault/key {vault_key_sealed, vault_key_recovery?}: alleen verzegelde blobs, atomair vervangen. Altijd toegestaan (herstel).
GET /vault/items?since=<revision>&limit=500 {items: [{id, revision, deleted, blob, updated_at}], revision}. Vereist een actief abonnement.
POST /vault/items {base_revision, items: [{id, blob|null}]} → {revision, conflicts: []}. blob: null verwijdert (grafsteen). Als base_revision verouderd is, geeft de server newer_items terug in plaats van te schrijven. Maximaal 500 items per verzending. Vereist een actief abonnement.

Abonnement

Elk account start in trial voor 30 dagen. De synchronisatieroutes antwoorden 402 subscription_required bij het verlopen; de verzegelde kluissleutel blijft leesbaar om een herstel mogelijk te maken. De client toont "In afwachting" en gaat lokaal verder.

Foutcodes

Code HTTP Betekenis
invalid_credentials 401 E-mail, sleutel of code onjuist.
unauthenticated 401 Token ontbreekt, is verlopen of apparaat ingetrokken.
email_unverified 403 E-mailcode niet ingevoerd.
totp_required 403 Geef totp op.
subscription_required 402 Cloud-abonnement verlopen.
email_taken 409 Er bestaat al een geverifieerd account met dit e-mailadres.
stale_revision 409 Haal eerst de teruggegeven newer_items op.
token_reused 401 Herhaling gedetecteerd, apparaat ingetrokken.

Snelheidslimieten

Pre-login 30/min, registratie en verificatie 10/min, aanmelden 15/min, vernieuwen 30/min, geauthenticeerde routes 240/min per apparaat.

Voorbeeld

curl -s https://api.rempar.org/v1/auth/prelogin \
  -H 'Content-Type: application/json' \
  -d '{"email":"vous@example.org"}'

Een vraag die hier niet wordt beantwoord? support@rempar.org