API-Referenz

Basis: https://api.rempar.org/v1. Überall JSON. Erfolgreiche Antworten sind in {"data": ...} verpackt, Fehler in {"error": {"code": "...", "message": "..."}}. Authentifizierung per Bearer-Token, eigenes Token für jedes Gerät.

Die API ist Zero-Knowledge: Sie erhält nie ein Passwort und nie Inhalte im Klartext. Clients von Drittanbietern sind willkommen, solange sie das Protokoll v1 einhalten.

Status

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

Authentifizierung

Methode Route Body Antwort
POST /auth/prelogin {email} {kdf, kdf_salt}. Deterministisches Schein-Salt, wenn die E-Mail-Adresse unbekannt ist.
POST /auth/register {email, auth_key, kdf, kdf_salt, device} 201 {status: "verification_sent"}. Ein sechsstelliger Code wird per E-Mail gesendet.
POST /auth/verify-email {email, code} {}
POST /auth/login {email, auth_key, device, totp?, code?} {tokens, device_id, vault_key_sealed?}. Fehler totp_required (403), wenn die 2FA aktiv ist und der Code fehlt. Danach email_code_required (403): Ein sechsstelliger Code wird per E-Mail gesendet und muss in code zurückgegeben werden, um die Tokens zu erhalten (10 Min., 5 Versuche).
POST /auth/refresh {refresh_token} {access_token, refresh_token, ...}. Rotation; eine Wiederverwendung widerruft das Gerät.
POST /auth/logout Widerruft das aktuelle Gerät.
POST /auth/recover {email, recovery_auth, totp?} Nachweis des Wiederherstellungskits: liefert {vault_key_recovery, recovery_token} (15 Min.). totp_required, wenn die 2FA aktiv ist.
POST /auth/recover/complete {email, recovery_token, auth_key, kdf, kdf_salt, vault_key_sealed, device} Neues Master-Passwort: ersetzt den Authentifizierungsschlüssel und den neu versiegelten Tresorschlüssel, widerruft alle anderen Geräte, meldet dieses an ({tokens, device_id, vault_key_sealed}).

device: {name, platform, client_id}, wobei client_id eine vom Client gewählte UUID ist, stabil für dieses Gerät.

kdf: {"algo": "argon2id", "m": 65536, "t": 3, "p": 4}. Die Clients lehnen Parameter ab, die schwächer sind als m=19456, t=2, p=1.

Konto

Methode Route Beschreibung
GET /account E-Mail-Adresse, 2FA-Status, Tresor-Revision, Abo {plan, active, until}.
GET /account/subscription Nur das Abo.
POST /account/password Ersetzt auth_key nach einer Änderung des Master-Passworts. Der Client veröffentlicht zuvor den neu versiegelten Tresorschlüssel.
GET /account/devices Aktive Geräte.
DELETE /account/devices/{id} Widerruft ein Gerät.
POST /account/totp/setup Erzeugt ein Geheimnis und liefert {secret, otpauth_url}.
POST /account/totp/enable {code}: aktiviert die 2FA.
POST /account/totp/disable {code}: deaktiviert die 2FA.

Tresor

Methode Route Beschreibung
PUT /vault/key {vault_key_sealed, vault_key_recovery?}: nur versiegelte Blobs, atomar ersetzt. Immer erlaubt (Wiederherstellung).
GET /vault/items?since=<revision>&limit=500 {items: [{id, revision, deleted, blob, updated_at}], revision}. Erfordert ein aktives Abo.
POST /vault/items {base_revision, items: [{id, blob|null}]} → {revision, conflicts: []}. blob: null löscht (Grabstein). Ist base_revision veraltet, liefert der Server newer_items, statt zu schreiben. Höchstens 500 Einträge pro Übertragung. Erfordert ein aktives Abo.

Abo

Das Cloud-Abo beginnt mit einer kostenlosen 7-tägigen Testphase (trial), gestartet über Stripe, den App Store oder Google Play (siehe GET /v1/account/subscription). Ohne aktives Abo antworten die Synchronisierungsrouten mit 402 subscription_required; der versiegelte Tresorschlüssel bleibt lesbar, damit eine Wiederherstellung möglich ist. Der Client zeigt „Ausstehend“ an und arbeitet lokal weiter.

Fehlercodes

Code HTTP Bedeutung
invalid_credentials 401 E-Mail-Adresse, Schlüssel oder Code falsch.
unauthenticated 401 Token fehlt, ist abgelaufen oder das Gerät wurde widerrufen.
email_unverified 403 E-Mail-Code nicht eingegeben.
totp_required 403 totp angeben.
subscription_required 402 Cloud-Abo abgelaufen.
email_taken 409 Für diese E-Mail-Adresse existiert bereits ein bestätigtes Konto.
stale_revision 409 Zuerst die zurückgegebenen newer_items abholen.
token_reused 401 Wiederverwendung erkannt, Gerät widerrufen.

Ratenbegrenzung

Pre-Login 30/Min., Registrierung und Bestätigung 10/Min., Anmeldung 15/Min., Refresh 30/Min., authentifizierte Routen 240/Min. pro Gerät.

Beispiel

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

Ihre Frage wird hier nicht beantwortet? support@rempar.org