Build a mobile app

Client setup

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()

Customer login & tokens

• Store the new pair on every refresh, in the system’s secure storage: Keychain on iOS, a value encrypted with an Android Keystore key on Android, flutter_secure_storage in Flutter. Write both tokens before using the new access token.
• One refresh at a time: requests that get a 401 together wait for the same refresh instead of each starting their own.
• Reuse: if the app is killed between the response and the save, on restart it presents the old token. Within 60 seconds the API returns the same current token; later, for a customer account, it still returns the session’s current token. No forced logout, as long as you store what you receive.
• End of session: a 401 from /auth/refresh (auth.session_revoked, auth.refresh_token_reused, auth.refresh_token_invalid) or a 403 auth.tenant_unavailable ends the session: clear the tokens and show the login screen.
• No network or 5xx: don’t clear anything, try again later.

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

/// One refresh at a time: whoever arrives during a refresh awaits the same 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"];
    // The old token is already superseded: ALWAYS store the new pair.
    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") {
      // Session closed: back to login.
      await storage.delete(key: "refresh_token");
      await storage.delete(key: "access_token");
    }
    return null; // network or 5xx: the tokens stay, try again later
  }
}

Logout

• Sign out: if you registered the device for notifications, first call DELETE /devices/{device_id} with the access token (a device linked to the account can only be removed by its owner). Then POST /auth/logout with {"refresh_token": "..."} in the body closes this device’s session on the server. Finally clear the tokens.
• Sign out everywhere: POST /auth/logout?all=true with the access token (or the refresh token in the body). From then on every token issued before answers 401 auth.session_revoked.

Two-factor authentication (2FA)

1. POST /auth/login answers 401 auth.totp_required: show the code field.
2. Repeat the same call with totp_code. The same field accepts a recovery code xxxxx-xxxxx: offer a “Lost your phone? Use a recovery code” link. Each code is valid only once (401 auth.totp_invalid if reused).

• POST /auth/2fa/setup with the current password returns secret and qr_uri; on mobile, also offer a button that opens qr_uri in the authenticator app.
• POST /auth/2fa/verify with code and current_password enables 2FA and answers with new tokens (the other sessions are closed: store them) and with 10 recovery_codes. Show them only once, with “Copy” and “Share”, and ask the customer to confirm they saved them.
• GET /auth/me exposes recovery_codes_remaining: when it gets close to 0, offer to regenerate them with POST /auth/2fa/recovery-codes (the current password is required).
• POST /auth/2fa/disable accepts the app code or a recovery code and also returns new tokens to store.

Push notifications