Skip to Content
Faable AuthQuickstartsJavaScript (Vanilla)

JavaScript Quickstart 🟨

Add a complete login experience to a plain JavaScript single-page app — no framework. @faable/auth-js drives the Authorization Code flow with PKCE, stores the session, refreshes tokens, and syncs across tabs. You wire it to the DOM with one subscription.

This is the framework-agnostic core pattern: createClient + onAuthStateChange + getSession. The Vue, SvelteKit, and Angular quickstarts are the same three calls wired into each framework’s reactivity.

You need one package: @faable/auth-js — no framework helper required.


✅ Prerequisites

In the Faable Dashboard , create a Client for your SPA and configure:

  • Allowed Callback URLs: http://localhost:5173/callback (add your production URL later).
  • Allowed Logout URLs: http://localhost:5173.
  • Allowed Web Origins: http://localhost:5173.

Note your auth domain (your-domain.auth.faable.link) and Client ID. SPAs are public clients — no client secret is involved.


🛠️ Step 1: Create the App and Install

npm create vite@latest my-app -- --template vanilla-ts cd my-app npm install @faable/auth-js

Step 2: Create the Auth Client

// src/auth.ts import { createClient } from '@faable/auth-js' export const auth = createClient({ domain: 'your-domain.auth.faable.link', clientId: 'YOUR_CLIENT_ID', redirectUri: window.location.origin + '/callback' })

The client initializes itself on creation: it recovers an existing session from storage, or — on the callback URL — exchanges the PKCE ?code= for tokens.

Step 3: Render on Auth State

Subscribe once with onAuthStateChange and re-render whenever the session changes — login, logout, token refresh, or a change in another tab. getSession() returns the current session (and auto-refreshes it if expired).

// src/main.ts import { auth } from './auth' const app = document.querySelector<HTMLDivElement>('#app')! async function render() { // On the callback route, finish the login and go home (Step 5) if (location.pathname === '/callback') { const { error, returnTo } = await auth.handleRedirectCallback() if (error) return void (app.textContent = `Sign-in failed: ${error.message}`) return void location.replace(returnTo ?? '/') } const { data } = await auth.getSession() if (!data.session) { app.innerHTML = `<button id="login">Sign in</button>` document .querySelector('#login')! .addEventListener('click', () => auth.signIn()) return } app.innerHTML = ` <p>Hello ${data.session.user.email}</p> <button id="logout">Sign out</button>` document .querySelector('#logout')! .addEventListener('click', () => auth.signOut({ scope: 'global', returnTo: location.origin }) ) } // Re-render on every auth change, then do the first render. auth.onAuthStateChange(() => render()) render()
  • signIn() sends the user to your tenant’s Universal Login with every connection you’ve enabled. Target one directly with signInWithOauthConnection({ connection_id: "connection_..." }).
  • signOut({ scope: 'global', returnTo }) clears the local session and the SSO cookie on the auth server, so the user is signed out of every app on your tenant. signOut() alone signs out of this app only: it revokes this app’s refresh token and stays on the page. returnTo must be in Allowed Logout URLs.
  • Both methods redirect the browser on success — the promise intentionally never resolves, so don’t put code after the await.

Step 4: Add the Callback Route

The render() above already handles /callback by calling handleRedirectCallback(). In a Vite SPA, make sure a request to /callback serves the same index.html (add a rewrite in vite.config.ts, or use hash routing). handleRedirectCallback() awaits the code-for-tokens exchange (it’s idempotent — the client already started it) and returns { error, returnTo }, so deep links survive the login round-trip if you passed returnTo to signInWithOauthConnection({ returnTo }).

Step 5: Call Your API

The access token lives on the session. Read it fresh before each call — getSession() auto-refreshes an expired session:

// src/api.ts import { auth } from './auth' export async function apiFetch(path: string) { const { data, error } = await auth.getSession() if (error || !data.session) throw new Error('Not signed in') return fetch(`https://api.myapp.com${path}`, { headers: { authorization: `Bearer ${data.session.access_token}` } }) }

If your backend validates the token’s audience, pass your API identifier when creating the client (createClient({ ..., audience: "https://api.myapp.com" })) — and see Validate Access Tokens for the Express middleware on the other side.


❓ FAQ

How do I get the access token in plain JavaScript?

From the session: const { data } = await auth.getSession(), then data.session?.access_token. There is no separate getAccessToken() — getSession() already refreshes expired tokens before returning.

How do I read custom claims (roles, tenant, station…) in the client?

Two ways, both fed by the same access token:

  • session.user already carries the custom claims your tenant puts on the token (an Action’s api.accessToken.setCustomClaim or a connection’s claims_mapping) as top-level properties, because /me returns them: data.session.user['ciapol.com/station_id'].
  • auth.getClaims<{ 'ciapol.com/station_id': string }>() decodes the token locally (standard claims like sub, scope, exp plus your custom ones) and refreshes an expired session first, like getSession(). auth.getClaim('ciapol.com/station_id') returns a single value or null.

Claims are decoded, not signature-verified: use them for UI and routing, never as authorization — the API that receives the token is what validates it. See Actions.

Do I need a framework or a build step?

No. @faable/auth-js is framework-agnostic and works with any bundler (Vite here) or plain ES modules. The React, Vue, SvelteKit, and Angular quickstarts wire the same client into each framework.

How do I send users straight to one provider?

Pass connection_id to signInWithOauthConnection — e.g. { connection_id: "connection_..." }. Find the ID in Dashboard → Auth → Connections. Without it, users pick on the Universal Login screen.

Why doesn’t the sign-in promise resolve?

signIn and signOut({ scope: 'global' }) redirect the browser on success, so the page unloads before the promise settles. Put post-login logic in the onAuthStateChange handler, not after the await.


Last updated on