Riferimento dell'API

Base: https://api.rempar.org/v1. JSON ovunque. Le risposte riuscite sono racchiuse in {"data": ...}, gli errori in {"error": {"code": "...", "message": "..."}}. Autenticazione tramite token Bearer proprio di ciascun dispositivo.

L'API è a conoscenza zero: non riceve mai password né contenuti in chiaro. I client di terze parti sono benvenuti purché rispettino il protocollo v1.

Stato

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

Autenticazione

Metodo Route Corpo Risposta
POST /auth/prelogin {email} {kdf, kdf_salt}. Sale fittizio deterministico se l'e-mail è sconosciuta.
POST /auth/register {email, auth_key, kdf, kdf_salt, device} 201 {status: "verification_sent"}. Un codice a sei cifre viene inviato per e-mail.
POST /auth/verify-email {email, code} {}
POST /auth/login {email, auth_key, device, totp?, code?} {tokens, device_id, vault_key_sealed?}. Errore totp_required (403) se la 2FA è attiva e il codice è assente. Poi email_code_required (403): un codice a sei cifre viene inviato per e-mail e va rinviato in code per ottenere i token (10 min, 5 tentativi).
POST /auth/refresh {refresh_token} {access_token, refresh_token, ...}. Rotazione; un riutilizzo revoca il dispositivo.
POST /auth/logout Revoca il dispositivo corrente.
POST /auth/recover {email, recovery_auth, totp?} Prova del kit di emergenza: restituisce {vault_key_recovery, recovery_token} (15 min). totp_required se la 2FA è attiva.
POST /auth/recover/complete {email, recovery_token, auth_key, kdf, kdf_salt, vault_key_sealed, device} Nuova password principale: sostituisce la chiave di autenticazione e la chiave della cassaforte risigillata, revoca tutti gli altri dispositivi e connette questo ({tokens, device_id, vault_key_sealed}).

device: {name, platform, client_id} dove client_id è un UUID scelto dal client, stabile per questo dispositivo.

kdf: {"algo": "argon2id", "m": 65536, "t": 3, "p": 4}. I client rifiutano parametri più deboli di m=19456, t=2, p=1.

Account

Metodo Route Descrizione
GET /account E-mail, stato 2FA, revisione della cassaforte, abbonamento {plan, active, until}.
GET /account/subscription Solo l'abbonamento.
POST /account/password Sostituisce auth_key dopo un cambio di password principale. Il client ripubblica prima la chiave della cassaforte sigillata di nuovo.
GET /account/devices Dispositivi attivi.
DELETE /account/devices/{id} Revoca un dispositivo.
POST /account/totp/setup Genera un segreto e restituisce {secret, otpauth_url}.
POST /account/totp/enable {code}: attiva la 2FA.
POST /account/totp/disable {code}: disattiva la 2FA.

Cassaforte

Metodo Route Descrizione
PUT /vault/key {vault_key_sealed, vault_key_recovery?}: solo blob sigillati, sostituiti atomicamente. Sempre autorizzato (ripristino).
GET /vault/items?since=<revision>&limit=500 {items: [{id, revision, deleted, blob, updated_at}], revision}. Richiede un abbonamento attivo.
POST /vault/items {base_revision, items: [{id, blob|null}]} → {revision, conflicts: []}. blob: null elimina (lapide). Se base_revision è obsoleta, il server restituisce newer_items invece di scrivere. Massimo 500 elementi per invio. Richiede un abbonamento attivo.

Abbonamento

Ogni account inizia in trial per 30 giorni. Le route di sincronizzazione rispondono 402 subscription_required alla scadenza; la chiave della cassaforte sigillata resta leggibile per consentire un ripristino. Il client mostra "In attesa" e continua in locale.

Codici di errore

Codice HTTP Significato
invalid_credentials 401 E-mail, chiave o codice errato.
unauthenticated 401 Token assente, scaduto o dispositivo revocato.
email_unverified 403 Codice e-mail non inserito.
totp_required 403 Fornire totp.
subscription_required 402 Abbonamento Cloud scaduto.
email_taken 409 Account già verificato con questa e-mail.
stale_revision 409 Recuperare prima i newer_items restituiti.
token_reused 401 Riutilizzo rilevato, dispositivo revocato.

Limiti di frequenza

Pre-login 30/min, registrazione e verifica 10/min, accesso 15/min, aggiornamento 30/min, route autenticate 240/min per dispositivo.

Esempio

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

Una domanda senza risposta qui? support@rempar.org