Module 4 — Integrate Your App

Learning objectives

• Initialize @faable/auth-js and start a login.
• Handle the callback and read the session + user.
• Know which SDK to reach for in browser vs server vs React.

The client SDK: @faable/auth-js

For browsers and React Native. It runs the Authorization Code + PKCE flow, manages the session, and refreshes tokens. You only need your tenant domain and Client ID.

import { createClient } from "@faable/auth-js";
 
export const auth = createClient({
  domain: "your-tenant.auth.faable.link",
  clientId: "<your_client_id>",
});

Start a login

await auth.signInWithOauthConnection({
  redirectTo: "https://app.example.com/callback", // must be in Allowed Callback URLs
});

This redirects the browser to Faable’s /authorize with PKCE, state, and nonce already set up. The user authenticates via whatever connections you enabled.

Handle the callback

On your callback route, let the SDK finish the exchange:

// at https://app.example.com/callback
const { session } = await auth.handleRedirectCallback();
// session has the tokens; the user is now signed in

Read session & user

const session = await auth.getSession();        // null if not signed in
const accessToken = session?.access_token;       // forward this to YOUR APIs
const user = session?.user;                       // identity from the ID token

Apply Module 1 here: session.user comes from the ID token (who the user is). session.access_token is what you put in Authorization: Bearer … when calling your own backend. Don’t mix them up.

Log out

await auth.signOut(); // clears the local session; see OIDC Logout for RP-initiated

For logging out across every app the user signed into, see OIDC Logout.

The Faable SDK family — pick the right one

A quick win: the Next.js Quickstart wires all of this in an App Router project.

Common integration mistakes

• ❌ Sending the ID token to your API. Send the access token.
• ❌ Forgetting to add the prod callback URL → works locally, breaks in prod.
• ❌ Hardcoding tokens or putting a client secret in a browser app (public clients have no secret — PKCE replaces it).
• ❌ Calling APIs with an access token whose aud is not your API → the resource server rejects it (Module 5).

Check yourself

1. After handleRedirectCallback(), where do you get the value to call your own /api/orders backend?
2. Your login redirects fine locally but errors after deploying. Most likely cause?
3. Which package would a Node.js cron job use to update users — and why not @faable/auth-js?

Next: Module 5 — Server-side & Management API.