Firebase Auth Backup

Allow customers to use their existing Firebase Authentication to authenticate into a secure enclave that holds the encryption key for the user. The Portal SDK leverages Firebase ID tokens to securely store and retrieve encryption keys from the secure enclave.

How it works

Your app signs the user in with Firebase Auth (Email/Password, Google Sign-In, Phone, or any other Firebase Auth provider).
You configure the Portal SDK with a callback that returns a fresh Firebase ID token.
During backup, the SDK encrypts the client backup share and stores the encryption key in the secure enclave, authenticated by the Firebase ID token.
During recovery, the SDK retrieves the encryption key from the secure enclave using the same authentication, then decrypts the backup share to restore the wallet.

Security model

The secure enclave is Portal’s Trustless Backup Service (TBS) at backup.web.portalhq.io. Every Portal SDK calls it directly from the user’s device. The only secret it stores is the encryption key for each client’s backup. It never stores key shares, encrypted backups, or Firebase tokens. Alongside the key it keeps the Portal client ID and a hash of the bound Firebase UID (see below).

Piece	Where it lives
Encrypted client backup share	Portal, with Portal-Managed Backups, or your own storage with Self-Managed Backups
Encryption key	Trustless Backup Service
Decryption	The user’s device

The encryption key is a random 256-bit AES-GCM key generated on the device for each backup. Portal’s main API never receives the key, and the Trustless Backup Service never receives the encrypted share.

How requests are authorized

Every request to the Trustless Backup Service carries two credentials, and both must be valid:

The Portal client credential (Client API Key or Client Session Token) identifies the Portal client.
The Firebase ID token identifies the user. The service verifies its signature against Google’s public keys, checks that it has not expired, and requires its issuer and audience to match the Firebase project ID you registered for the environment.

On the first successful request, the service binds that Firebase user to the Portal client and stores a SHA-256 hash of the Firebase UID, never the raw UID. After that, requests for the client from any other Firebase user are rejected. A Portal credential alone cannot read the key, and neither can a valid Firebase token for a different user.

How the key is protected

The Trustless Backup Service runs in AWS Nitro Enclaves, on infrastructure separate from Portal’s main API.
TLS terminates inside the enclave.
Stored keys are envelope-encrypted with AWS KMS, and the key policy only allows decryption from an attested enclave running Portal’s approved build.

Integration requirements

Keep one Portal client per user. The key is bound to the Portal client. When a user recovers on a new device, authenticate as their existing client instead of creating a new one.
Keep the Firebase UID stable. If a user signs in with a provider that creates a new Firebase user instead of linking to the existing account, recovery fails with 403. Use Firebase account linking for users with more than one sign-in provider.
Backing up again replaces the key. Each backup stores a new key for the client.
Firebase backup keys cannot be deleted. The Trustless Backup Service has no delete operation.
Register your Firebase project in every environment you use, including production.

Errors

Status	Message	Cause
`401`	`X-Firebase-Token header required`	No Firebase ID token was sent. Check that `getToken` returns a token for the signed-in user.
`401`	`invalid Firebase token`	The token is expired, malformed, or from a different Firebase project. Make sure `getToken` returns a current ID token for the project you registered.
`401`	`Invalid token`	The Portal client credential was rejected, for example an expired Client Session Token.
`403`	`no Firebase auth configured for this custodian`	No Firebase project is registered for the environment.
`403`	`Firebase account does not match this client`	A different Firebase user than the one bound at backup time.
`404`	`no encryption key found for this backup method`	The client has no Firebase backup.

Prerequisites

A Firebase project with Firebase Authentication enabled.
At least one sign-in provider configured in Firebase Auth (Email/Password, Google Sign-In, Apple Sign-In, etc.).
Your Firebase project registered with Portal (see below).

Register your Firebase project with Portal

You must register your Firebase project with Portal so that the secure enclave can validate your users’ Firebase ID tokens.

Go to the Portal Dashboard.
Navigate to Configuration > Firebase Auth.
In the Firebase Backup Authentication Config section, enter your Firebase Project ID and save.

You can also register the JWT provider programmatically via the Custodian API:

curl -X POST https://api.portalhq.io/api/v3/custodians/me/jwt-provider \
  -H "Authorization: Bearer YOUR_CUSTODIAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "firebase",
    "projectId": "your-firebase-project-id"
  }'

Add Firebase to your app

iOS
Android
Flutter
Web

If you have not already set up Firebase in your iOS app, follow the Firebase iOS setup guide. At a minimum, you need to:

Add your iOS app in the Firebase Console.
Download the GoogleService-Info.plist file and add it to your Xcode project.
Add the FirebaseAuth dependency via Swift Package Manager or CocoaPods.
Call FirebaseApp.configure() in your AppDelegate or app entry point.

If you have not already set up Firebase in your Android app, follow the Firebase Android setup guide. At a minimum, you need to:

Add your Android app in the Firebase Console.
Download the google-services.json file and add it to your app/ directory.
Add the Firebase dependencies to your build.gradle:

dependencies {
    implementation platform("com.google.firebase:firebase-bom:33.1.0")
    implementation "com.google.firebase:firebase-auth-ktx"
    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-play-services:1.7.3"
}

Apply the Google services plugin:

// In your project-level build.gradle
plugins {
    id "com.google.gms.google-services" version "4.4.2" apply false
}

// In your app-level build.gradle
plugins {
    id "com.google.gms.google-services"
}

If you have not already set up Firebase in your Flutter app, follow the FlutterFire setup guide. At a minimum, you need to:

Install the FlutterFire CLI: dart pub global activate flutterfire_cli
Run flutterfire configure to connect your Flutter app to your Firebase project.
Add the firebase_core and firebase_auth packages to your pubspec.yaml:

dependencies:
  firebase_core: ^3.0.0
  firebase_auth: ^5.0.0
  portal_flutter: ^X.X.X

Initialize Firebase in your app entry point:

import 'package:firebase_core/firebase_core.dart';
import 'firebase_options.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp(
    options: DefaultFirebaseOptions.currentPlatform,
  );
  runApp(MyApp());
}

If you have not already set up Firebase in your web app, follow the Firebase Web setup guide. At a minimum, you need to:

Add a Web app in the Firebase Console and copy your Firebase config (apiKey, authDomain, projectId, etc.).
Install the Firebase JavaScript SDK:

npm install firebase

Initialize Firebase in your app (for example in your root layout or entry module):

import { initializeApp, getApps } from 'firebase/app'
import { getAuth } from 'firebase/auth'

const firebaseConfig = {
  apiKey: process.env.NEXT_PUBLIC_FIREBASE_API_KEY,
  authDomain: process.env.NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN,
  projectId: process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID,
}

const app = getApps().length ? getApps()[0]! : initializeApp(firebaseConfig)
export const firebaseAuth = getAuth(app)

Sign users in with any Firebase Auth provider your app supports (Email/Password, Google, etc.) before calling Portal backup or recovery with BackupMethods.firebase.

Supported platforms

Firebase Auth Backup is currently available on:

iOS - See the iOS Back up a wallet guide
Android - See the Android Back up a wallet guide
Flutter - See the Flutter Back up a wallet guide
React Native - See the React Native Back up a wallet guide
Web - See the Web Back up a wallet guide

Getting Started

SDKs

APIs

Integrations

Resources

Firebase Auth Backup

How it works

Security model

How requests are authorized

How the key is protected

Integration requirements

Errors

Prerequisites

Register your Firebase project with Portal

Add Firebase to your app

Supported platforms

​How it works

​Security model

​How requests are authorized

​How the key is protected

​Integration requirements

​Errors

​Prerequisites

​Register your Firebase project with Portal

​Add Firebase to your app

​Supported platforms

How it works

Security model

How requests are authorized

How the key is protected

Integration requirements

Errors

Prerequisites

Register your Firebase project with Portal

Add Firebase to your app

Supported platforms