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