Zero-backend federated identity

If your app already signs users in with Firebase, Supabase, Auth0, Cognito, Clerk, or any OIDC provider, you can call Roadie as the signed-in user with no backend of your own. Roadie exchanges your identity provider’s ID token for a short-lived client token scoped to that one end user — this is Path B, the differentiator. Your auth system stays the root of trust; Roadie never sees your user database. This tutorial wires it up in an Expo / React Native app with Firebase Auth, using the SDK’s federatedTokenProvider. The same pattern works in any browser or mobile app on @roadie/sdk.

No permanent secret ever ships in the app. The device sends its existing ID token plus your publishable key (rd_pk_…), which can do nothing but mint. See why this is safe in Client tokens.

How it works

Firebase Auth  ──ID token──▶  federatedTokenProvider  ──exchange──▶  Roadie client token
 (your root of trust)          (SDK helper, publishable key)   POST /v1/client-tokens   (one end user)
                                                                          │
                                            new Roadie({ tokenProvider }) ─┴─▶ gateway (per-user limits)

The gateway verifies the ID token against your IdP’s JWKS — strict exact-issuer and audience checks, asymmetric algorithms only — extracts the end-user id (and optional plan claim), and mints.

Prerequisites

An existing IdP that issues ID tokens (JWTs) — this tutorial uses Firebase Auth.
A Roadie project with a validated provider credential (OpenAI or Anthropic — BYOK).
A publishable key (rd_pk_…) for the environment you will call.

1. Configure federated auth on the project

In the dashboard, configure the project’s federated auth with your IdP’s details:

Issuer — the exact iss your IdP stamps (for Firebase, https://securetoken.google.com/<project-id>).
JWKS URL — where the gateway fetches the IdP’s public verification keys.
Audience — the aud your tokens carry (for Firebase, your Firebase project id).
Claim mapping — which claim is the end-user id (e.g. sub or user_id), and optionally which claim carries the plan.

A known-public issuer (Firebase, Auth0, Cognito, …) requires an audience. Without one, any token that shared IdP mints for any app would be accepted — the confused-deputy trap — so the dashboard refuses to save the config. Always set aud.

2. Install the SDK

npx expo install @roadie/sdk

The SDK is isomorphic and has zero runtime dependencies, so it runs in Expo / React Native unchanged.

3. Wire `federatedTokenProvider`

Hand the SDK a tokenProvider that performs the exchange. You give it your publishable key, the gateway base URL, and a function that returns the user’s current ID token; the SDK caches the minted token and refreshes it at ~80% of its TTL, single-flighting concurrent refreshes.

roadie.ts

import { Roadie, federatedTokenProvider } from '@roadie/sdk';
import { getAuth } from 'firebase/auth';

const auth = getAuth();
const GATEWAY = 'https://gateway.roadie.paroaria.ai';

export const roadie = new Roadie({
  baseUrl: GATEWAY,
  tokenProvider: federatedTokenProvider({
    baseUrl: GATEWAY,
    publishableKey: 'rd_pk_prod_…',
    // Roadie exchanges this Firebase ID token for a per-user client token.
    getIdentityToken: () => auth.currentUser!.getIdToken(),
  }),
});

Under the hood the provider POSTs to /v1/client-tokens with the publishable key as the bearer and { identity_token } in the body; the gateway distinguishes Path B from the secret-key Path A by the credential kind.

4. Call Roadie as the signed-in user

From here the API is identical to the server tutorials — but every call is authenticated as the signed-in end user, with that user’s limits and quotas, and no secret key in the app:

chat.ts

import { roadie } from './roadie';

export async function streamReply(prompt: string, onDelta: (t: string) => void) {
  for await (const event of roadie.chat.stream({
    model: 'openai/gpt-4o',
    messages: [{ role: 'user', content: prompt }],
  })) {
    if (event.type === 'content_delta') onDelta(event.delta);
  }
}

You do not pass user here — the end-user id is carried in the token, derived from your IdP’s claim mapping. (If you do pass user, it must match the token or be omitted.)

5. The plan is decided at the server

Whatever plan your IdP asserts in the token, the mint uses the effective entitlement Roadie holds for that end user when one exists — the developer-authoritative tier always wins, and a client can never raise its own tier by asserting a higher plan. The asserted claim is only a fallback when no entitlement is on record. So you can still gate Pro features server-side: grant the entitlement with your secret key (for example from a purchase webhook), exactly as in Free → Pro with StoreKit — the difference is only where the end-user id comes from.

6. Verify

Sign in, send a message, and open the dashboard’s request logs. The request is attributed to the end-user id your claim mapping selected (e.g. the Firebase sub), and per-user limits apply. If the exchange fails:

400 federated_auth_not_configured — finish step 1 for this project.
401 invalid_identity_token — the ID token failed issuer/audience/signature verification; re-check the issuer, aud, and JWKS URL.

Why this is safe

No secret ships. The publishable key can only mint — and a leaked one mints nothing without a valid ID token from your IdP.
Short blast radius. Client tokens live at most an hour and are scoped to one end user’s limits.
Your DB stays yours. Roadie verifies tokens against your JWKS and never sees your user records.
Cut off a session by blocking the end user — the gateway’s denylist rejects that user within a second, and the short TTL does the rest. There is no per-token revocation to manage.

What you built

Your app calls Roadie directly as each signed-in user — chat, embeddings, and images scoped to that user’s own limits — with no backend of your own and no secret in the binary. Your existing Firebase (or Auth0 / OIDC) login is the sole root of trust; Roadie exchanges its ID token for a short-lived client token and enforces per-user limits from there.

Next steps

Per-user limits

Give each federated user their own rate limits and quotas.

Free → Pro with StoreKit

Gate premium features by granting a server-side entitlement.

Client tokens

Minting paths, scopes, TTLs, and the safety model.

App Attest device sign-in

No IdP at all? Authenticate the device itself instead.

​How it works

​Prerequisites

​1. Configure federated auth on the project

​2. Install the SDK

​3. Wire federatedTokenProvider

​4. Call Roadie as the signed-in user

​5. The plan is decided at the server

​6. Verify

​Why this is safe

​What you built

​Next steps

Per-user limits

Free → Pro with StoreKit

Client tokens

App Attest device sign-in

How it works

Prerequisites

1. Configure federated auth on the project

2. Install the SDK

3. Wire `federatedTokenProvider`

4. Call Roadie as the signed-in user

5. The plan is decided at the server

6. Verify

Why this is safe

What you built

Next steps