Costruisci un'app mobile

Setup del client

final dio = Dio(BaseOptions(
  baseUrl: "https://api.vellaro.io/api/v1",
  headers: { "X-Vellaro-Key": "cx_pk_live_demo_XXXXXXXXXXXX" },
));
final res = await dio.get("/products", queryParameters: {"page": 1});

var req = URLRequest(url: URL(string: "https://api.vellaro.io/api/v1/products")!)
req.setValue("cx_pk_live_demo_XXXXXXXXXXXX", forHTTPHeaderField: "X-Vellaro-Key")

val req = Request.Builder()
  .url("https://api.vellaro.io/api/v1/products")
  .header("X-Vellaro-Key", "cx_pk_live_demo_XXXXXXXXXXXX")
  .build()

Login del cliente & token

• Salva la coppia nuova a ogni refresh, nello storage sicuro del sistema: Keychain su iOS, un valore cifrato con una chiave dell’Android Keystore su Android, flutter_secure_storage in Flutter. Scrivi entrambi i token prima di usare il nuovo access token.
• Un solo refresh alla volta: le richieste che ricevono 401 insieme aspettano lo stesso rinnovo invece di lanciarne uno ciascuna.
• Riuso: se l’app si chiude fra la risposta e il salvataggio, al riavvio presenta il token vecchio. Entro 60 secondi l’API restituisce lo stesso token corrente; più tardi, per un account cliente, restituisce comunque il token corrente della sessione. Nessun logout forzato, purché tu salvi quello che ricevi.
• Fine sessione: un 401 da /auth/refresh (auth.session_revoked, auth.refresh_token_reused, auth.refresh_token_invalid) o un 403 auth.tenant_unavailable chiudono la sessione: cancella i token e mostra il login.
• Rete assente o 5xx: non cancellare nulla, riprova più tardi.

const storage = FlutterSecureStorage(); // Keychain (iOS) / Keystore (Android)
Future<String?>? _refreshing;

/// Un solo refresh alla volta: chi arriva durante un rinnovo aspetta lo stesso Future.
Future<String?> refreshAccessToken(Dio dio) =>
    _refreshing ??= _doRefresh(dio).whenComplete(() => _refreshing = null);

Future<String?> _doRefresh(Dio dio) async {
  final refresh = await storage.read(key: "refresh_token");
  if (refresh == null) return null;
  try {
    final res = await dio.post("/auth/refresh", data: {"refresh_token": refresh});
    final data = res.data["data"];
    // Il token vecchio è già superato: salva SEMPRE la coppia nuova.
    await storage.write(key: "refresh_token", value: data["refresh_token"]);
    await storage.write(key: "access_token", value: data["access_token"]);
    return data["access_token"] as String;
  } on DioException catch (e) {
    final status = e.response?.statusCode;
    final code = e.response?.data?["error_code"];
    if (status == 401 || code == "auth.tenant_unavailable") {
      // Sessione chiusa: si torna al login.
      await storage.delete(key: "refresh_token");
      await storage.delete(key: "access_token");
    }
    return null; // rete o 5xx: i token restano, si riprova più tardi
  }
}

Logout

• Esci: se hai registrato il device per le notifiche, chiama prima DELETE /devices/{device_id} con l’access token (un device collegato all’account lo rimuove solo il suo proprietario). Poi POST /auth/logout con {"refresh_token": "..."} nel corpo chiude la sessione di questo dispositivo sul server. Infine cancella i token.
• Esci da tutti i dispositivi: POST /auth/logout?all=true con l’access token (o il refresh token nel corpo). Da quel momento ogni token emesso prima risponde 401 auth.session_revoked.

Verifica in due passaggi (2FA)

1. POST /auth/login risponde 401 auth.totp_required: mostra il campo del codice.
2. Ripeti la stessa chiamata con totp_code. Lo stesso campo accetta un codice di recupero xxxxx-xxxxx: offri un link «Hai perso il telefono? Usa un codice di recupero». Ogni codice vale una volta sola (401 auth.totp_invalid se riusato).

• POST /auth/2fa/setup con la password attuale restituisce secret e qr_uri; su mobile offri anche un pulsante che apre qr_uri nell’app di autenticazione.
• POST /auth/2fa/verify con code e current_password attiva la 2FA e risponde con i token nuovi (le altre sessioni si chiudono: salvali) e con 10 recovery_codes. Mostrali una sola volta, con «Copia» e «Condividi», e chiedi conferma che il cliente li abbia salvati.
• GET /auth/me espone recovery_codes_remaining: se scende vicino a 0, proponi di rigenerarli con POST /auth/2fa/recovery-codes (serve la password attuale).
• POST /auth/2fa/disable accetta il codice dell’app o un codice di recupero e restituisce anch’esso token nuovi da salvare.

Notifiche push