💡 Audience: Developers building consumer apps (web or mobile) on top of HyperBabel — who need real per-user authentication, not a sandbox API key pasted into a login screen.

Embedding HyperBabel into a mobile app traditionally meant shipping your hb_live_… key inside the binary. Anyone who decompiled the APK / IPA had full access to your org. Web apps had a similar story — you either built your own backend proxy or accepted that your network tab leaked the key.

The Customer Auth feature solves this. HyperBabel's backend mints per-end-user JWTs (1h access, 30d refresh) directly from your client's Firebase ID token — no hop through your own backend required. Your client apps hold only those JWTs. The org hb_live_… key stays server-side, in Secret Manager / Vault / Workers Secrets — and never leaves it.

How the flow works

[Client App] ──Sign in with Firebase──→ Firebase ID token
     │
     │ POST /customer/auth/firebase-exchange
     │ Authorization: Bearer <firebase-id-token>
     ▼
[HyperBabel API]  ── Google JWKS verify → org lookup → customer JWT
     │
     │ { access_token, refresh_token, ... }
     ▼
[Client App] ──Bearer <customer access token>──→ /chat, /video, /translate

This is the same pattern SendBird and Stream call "session tokens", and how Twilio's "Access Tokens" work. We picked it because it leaves identity and GDPR responsibility with you, but takes the painful "where do I keep the API key" question off the table. Firebase Auth users get an extra shortcut: HyperBabel verifies the Firebase ID token directly against Google's JWKS, so you don't need to build or operate a backend exchange function for the Firebase path.

Step 1 — Set up Firebase Auth

In the Firebase Console, enable Auth → Google + Apple sign-in. Add iOS and Android apps (if you're shipping mobile) or set up the Web SDK. Download the platform config files. Firebase handles passwordless OAuth, Apple's email-relay quirks, and account recovery for you.

Already on Auth0, Cognito, Supabase Auth, or your own email/password? Skip to the "Not using Firebase?" section near the end — the same Customer Auth feature works with any auth provider, just through a slightly different endpoint.

Step 2 — Register your Firebase project in the HyperBabel Console (one-time)

Open Dashboard → Customer Auth → Firebase Projects → Add Firebase project. You'll be asked for two things:

1. Your Firebase project ID — looks like my-app-prod (Firebase Console → Project settings → General → "Project ID").
2. A short-lived Firebase ID token that proves you own the project. The form offers two ways to get one (~2 minutes) — pick whichever fits:
• Method A (recommended, no app needed): enable Email/Password in Firebase Auth → add a temporary test user → run the provided curl (or PowerShell) snippet with that user's credentials → paste the printed idToken.
• Method B (already-running app): in any app that already uses Firebase Auth, sign in any user and log await auth().currentUser.getIdToken().

The console verifies the token against Google's JWKS, checks its aud claim equals the project ID you entered, then maps the project to your HyperBabel org. The token itself is discarded immediately — never stored. From this point on, any user signed in to this Firebase project can be exchanged for a HyperBabel customer JWT.

Step 3 — Call /customer/auth/firebase-exchange directly from your client

No backend, no Cloud Function. The client sends its Firebase ID token straight to HyperBabel:

React Native

import auth from '@react-native-firebase/auth';
import { GoogleSignin } from '@react-native-google-signin/google-signin';
import * as SecureStore from 'expo-secure-store';

// 1. Sign in with Google (Apple uses auth.AppleAuthProvider; same shape)
await GoogleSignin.hasPlayServices();
const { idToken: googleIdToken } = await GoogleSignin.signIn();
const credential = auth.GoogleAuthProvider.credential(googleIdToken);
await auth().signInWithCredential(credential);

// 2. Get a fresh Firebase ID token (force-refresh avoids edge-cases near expiry)
const firebaseIdToken = await auth().currentUser!.getIdToken(true);

// 3. Exchange for a HyperBabel customer JWT — direct, no backend hop
const res = await fetch(
  'https://api.hyperbabel.com/api/v1/customer/auth/firebase-exchange',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${firebaseIdToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ preferred_lang_cd: 'en' }),
  },
);
if (!res.ok) throw new Error('Token exchange failed');
const session = await res.json();

// 4. Store and use
await SecureStore.setItemAsync('hb_access', session.access_token);
await SecureStore.setItemAsync('hb_refresh', session.refresh_token);

Web (any framework)

import { getAuth, signInWithPopup, GoogleAuthProvider } from 'firebase/auth';

const auth = getAuth();
await signInWithPopup(auth, new GoogleAuthProvider());
const firebaseIdToken = await auth.currentUser!.getIdToken(true);

const res = await fetch(
  'https://api.hyperbabel.com/api/v1/customer/auth/firebase-exchange',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${firebaseIdToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ preferred_lang_cd: 'en' }),
  },
);
if (!res.ok) throw new Error('Token exchange failed');
const session = await res.json();
sessionStorage.setItem('hb_access', session.access_token);
sessionStorage.setItem('hb_refresh', session.refresh_token);

iOS (Swift)

The pattern matches: get the Firebase ID token via Auth.auth().currentUser?.getIDTokenForcingRefresh(true) (or the async/await variant) → URLSession POST to /customer/auth/firebase-exchange with Authorization: Bearer <token> → decode the response and store access_token in Keychain. No SDK dependency beyond FirebaseAuth and URLSession.

Step 4 — Send the customer JWT on every HyperBabel call

Every subsequent call to /chat, /video, /translate, /rtm, etc. carries:

Authorization: Bearer <customer_access_token>

The org API key never lives on the device or in browser storage.

Step 5 — A defensive runtime guard

In your client-side HTTP client, add one line that throws if any header value ever starts with hb_live_ or hb_test_:

function assertNoOrgApiKey(headers: Record<string, string>) {
  for (const v of Object.values(headers)) {
    if (typeof v === 'string' && (v.startsWith('hb_live_') || v.startsWith('hb_test_'))) {
      throw new Error('Refusing to send a HyperBabel org API key from a client app');
    }
  }
}

Now even an accidental future commit can't leak the key.

What customer JWTs can — and cannot — do

A customer JWT can call every SDK-facing endpoint — /chat, /unitedchat, /video, /translate, /rtm, /presence, /push, /storage, /users — exactly as the org API key could. It cannot reach /admin, /billing, or /auth/api-keys. So even a leaked customer JWT can't create new keys, read invoices, or change org-level settings.

Refresh, revoke, observe

• Refresh is direct from the client — POST /customer/refresh when the access token is within ~5 minutes of expiry. The refresh token never unlocks the org key, so this path doesn't need a backend hop. Each refresh rotates the pair atomically (the previous refresh token is revoked) and the new session row records the current device's user-agent and IP for audit.
• Revoke lives on your backend — POST /customer/revoke with the org API key wipes every active session for one external_user_id in under 60 seconds globally. Use this on log-out-everywhere, password-changed, or abuse signals.
• Observe in the Console — Dashboard → Customer Auth shows token settings, your registered Firebase projects, and a searchable end-user table with active session counts and a "Revoke all" button per user.

Not using Firebase? The backend-exchange pattern

If your users sign in via Auth0, Cognito, Supabase Auth, or your own email/password system, the Firebase shortcut doesn't apply — but the same Customer Auth feature still works through a small server-to-server exchange:

// Your backend (Worker / Lambda / Express) — org API key stays server-side
async function mintCustomerJwt(externalUserId: string, displayName?: string) {
  const r = await fetch('https://api.hyperbabel.com/api/v1/customer/issue-token', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.HYPERBABEL_API_KEY!}`,  // hb_live_…
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      external_user_id: externalUserId,
      display_name: displayName ?? null,
      preferred_lang_cd: 'en',
    }),
  });
  if (!r.ok) throw new Error('Token issue failed');
  return r.json();  // { access_token, refresh_token, expires_at, ... }
}

Authenticate the user with your auth provider on the server first, then call /customer/issue-token. Return the response straight to the client — refresh, revoke, and the runtime guard all work the same as in the Firebase flow.

Reference

• API reference (Swagger): hyperbabel.com/docs — full endpoint signatures for /customer/auth/firebase-exchange, /customer/issue-token, /refresh, /revoke, and /me.
• Postman: the /customer/* requests are pre-configured in the latest collection. Import.
• Console: Customer Auth settings — register Firebase projects, tune token lifetime, manage end-user sessions.