Class FaableAuthClient

constructor

• new FaableAuthClient(config: FaableAuthClientConfig): FaableAuthClient

  Creates a new authentication client bound to a Faable Auth tenant.

  The constructor kicks off FaableAuthClient.initialize in the background; you do not need to await anything before calling other methods. Prefer the createClient factory in app code — it has the same effect with less ceremony.

  Parameters

  • config: FaableAuthClientConfig

    Tenant settings. domain and clientId are required and throw synchronously when missing.

  Returns FaableAuthClient

  Example

  const auth = new FaableAuthClient({
    domain: '<faableauth_domain>',
    clientId: '<client_id>',
    redirectUri: window.location.origin
  })
  Copy

  See

  • Get Started with Faable Auth
  • Clients

Optionalaudience

domainUrl

redirectUri

Optionalscope

sessionCheckExpiryDays

tokenIssuer

session

• get session(): Session | null

  Cached session value last persisted by the client.

  This is a synchronous accessor that returns whatever the client has already loaded into memory. It can lag behind storage (for example, across tabs before the broadcast event arrives) and never triggers a refresh. Prefer FaableAuthClient.getSession when you need an authoritative value, especially on the server.

  Returns Session | null

  The cached Session or null if no user is signed in.

  See

  UserInfo

signInWithOauthConnection

• signInWithOauthConnection(
      credentials: SignInWithOAuthConnection,
  ): Promise<OAuthResponse>

  Starts an OAuth / social login by redirecting the browser to the tenant's /authorize endpoint for the chosen connection.

  In browsers the SDK redirects the current window unless skipBrowserRedirect is true; the call resolves to the authorization URL so you can drive the navigation yourself. PKCE is used by default in browsers, falling back to the implicit flow elsewhere. Prefer connection_id when known — the backend resolves it without an extra lookup; connection (by name) is kept for legacy tenants.

  Parameters

  • credentials: SignInWithOAuthConnection

  Returns Promise<OAuthResponse>

  Example

  await auth.signInWithOauthConnection({
    connection: 'google',
    redirectTo: 'https://app.example.com/callback'
  })
  Copy

  See

  • Connections
  • Authorization Code with PKCE

signInWithOtp

• signInWithOtp(
      data: { audience?: string; otp: string; username: string },
  ): Promise<AuthResponse>

  Completes a passwordless login by exchanging an OTP code for a session.

  Pair this with FaableAuthClient.signInWithPasswordless called with type: 'code'. On success the new session is persisted to storage and a SIGNED_IN event is broadcast.

  Parameters

  • data: { audience?: string; otp: string; username: string }

    The user identifier and the OTP code they received.

  Returns Promise<AuthResponse>

  Example

  const { data, error } = await auth.signInWithOtp({
    username: 'user@example.com',
    otp: '123456'
  })
  Copy

  See

  Passwordless Authentication

signInWithPasswordless

• signInWithPasswordless(
      data: { audience?: string; email: string; type: "code" | "link" },
  ): Promise<{ data: any; error: AuthError | null }>

  Starts a passwordless login flow by emailing the user either an OTP code or a magic link.

  • type: 'code' sends a short code the user pastes into your UI; finish the flow with FaableAuthClient.signInWithOtp.
  • type: 'link' sends a clickable link that lands on your redirectUri with the tokens already attached, processed by FaableAuthClient.initialize on page load.

  Parameters

  • data: { audience?: string; email: string; type: "code" | "link" }

    The user's email and the delivery mechanism.

  Returns Promise<{ data: any; error: AuthError | null }>

  Example

  await auth.signInWithPasswordless({
    email: 'user@example.com',
    type: 'code'
  })
  Copy

  See

  Passwordless Authentication

signInWithUsernamePassword

• signInWithUsernamePassword(
      data: {
          audience?: string;
          password: string;
          redirectTo?: string;
          state?: string;
          username: string;
      },
  ): Promise<{ data: null; error: AuthError | null }>

  Signs the user in with a username + password against a database connection on the tenant.

  The server responds with an HTML form that posts the user back to the tenant's /login/callback to complete the OAuth flow; the SDK auto-submits it from the current document. That is why the success path resolves to { data: null, error: null } — the actual session lands on the redirect target, not on this return value. Subscribe with FaableAuthClient.onAuthStateChange to observe the resulting SIGNED_IN event.

  Parameters

  • data: {
        audience?: string;
        password: string;
        redirectTo?: string;
        state?: string;
        username: string;
    }

  Returns Promise<{ data: null; error: AuthError | null }>

  Example

  await auth.signInWithUsernamePassword({
    username: 'user@example.com',
    password: '••••••••',
    redirectTo: 'https://app.example.com/callback'
  })
  Copy

  See

  Connections

authorize

• authorize(
      options: {
          audience?: string;
          redirectTo?: string;
          response_type: string;
          scope?: string;
      },
  ): void

  Redirects the current window to the tenant's /authorize endpoint.

  Fire-and-forget: there is no return value because the browser navigates away. The session lands back on your redirectUri, where FaableAuthClient.initialize consumes it on the next page load.

  Parameters

  • options: {
        audience?: string;
        redirectTo?: string;
        response_type: string;
        scope?: string;
    }

  Returns void

  Example

  auth.authorize({
    response_type: 'code',
    redirectTo: 'https://app.example.com/callback'
  })
  Copy

  See

  Authorization Code with PKCE

buildAuthorizeUrl

• buildAuthorizeUrl(
      options?: {
          audience?: string;
          connection?: string;
          redirectTo?: string;
          response_type?: string;
          scope?: string;
      },
  ): string

  Builds the tenant's /authorize URL without redirecting the browser.

  Useful when you need to render a login link, open the page in a popup, or hand the URL to a different runtime (e.g. a webview). For the everyday "click → redirect" flow use FaableAuthClient.authorize or FaableAuthClient.signInWithOauthConnection.

  The redirect target is resolved with this precedence: options.redirectTo → config.redirectUri → window.location.origin.

  Parameters

  • options: {
        audience?: string;
        connection?: string;
        redirectTo?: string;
        response_type?: string;
        scope?: string;
    } = {}

  Returns string

  The fully-qualified authorize URL.

  Example

  const url = auth.buildAuthorizeUrl({
    connection: 'google',
    redirectTo: 'https://app.example.com/callback'
  })
  window.open(url, 'login', 'popup')
  Copy

  See

  Authorization Code with PKCE

getSession

• getSession(): Promise<
      | { data: { session: Session }; error: null }
      | { data: { session: null }; error: AuthError }
      | { data: { session: null }; error: null },
  >

  Returns the session, refreshing it if necessary.

  The session returned can be null if no user is signed in or the last one has logged out.

  IMPORTANT: This method loads values directly from the storage attached to the client. If that storage is based on request cookies (for example, on the server) the values in it may not be authentic and therefore it's strongly advised against using this method and its results in such circumstances — a warning will be emitted when the storage exposes isServer: true. Re-fetch the user with a verified call (or verify the access token yourself) before trusting it.

  Returns Promise<
      | { data: { session: Session }; error: null }
      | { data: { session: null }; error: AuthError }
      | { data: { session: null }; error: null },
  >

  Example

  const { data, error } = await auth.getSession()
  if (data.session) console.log(data.session.user)
  Copy

  See

  UserInfo

onAuthStateChange

• onAuthStateChange(
      callback: (
          event: AuthChangeEvent,
          session: Session | null,
      ) => void | Promise<void>,
  ): { data: { subscription: Subscription } }

  Subscribes to auth-state changes for this client.

  The callback fires for INITIAL_SESSION once shortly after subscribing (so consumers don't have to special-case "no event yet"), and then for every SIGNED_IN, SIGNED_OUT, TOKEN_REFRESHED, PASSWORD_RECOVERY, and USER_UPDATED event. Events are broadcast across tabs through BroadcastChannel, so a sign-in or sign-out in one tab reaches every other tab using the same storageKey.

  Parameters

  • callback: (event: AuthChangeEvent, session: Session | null) => void | Promise<void>

    Invoked with the event name and the new session (or null on SIGNED_OUT). Can return a promise — the SDK awaits it.

  Returns { data: { subscription: Subscription } }

  { data: { subscription } } — call subscription.unsubscribe() to stop listening.

  Example

  const { data: { subscription } } = auth.onAuthStateChange((event, session) => {
    if (event === 'SIGNED_IN') console.log('Welcome', session?.user.email)
  })
  // later
  subscription.unsubscribe()
  Copy

  See

  Get Started with Faable Auth

refreshSession

• refreshSession(
      currentSession?: { refresh_token: string },
  ): Promise<AuthResponse>

  Forces a new session by exchanging a refresh token regardless of expiry.

  Normally the SDK handles refresh transparently via the auto-refresh ticker; call this only when you need to force an immediate refresh — e.g. right after a server-side action that changed the user's claims. Omit currentSession to reuse whatever FaableAuthClient.getSession returns.

  Parameters

  • OptionalcurrentSession: { refresh_token: string }

    Optional session shape carrying the refresh token to exchange. When passed it must include refresh_token.

  Returns Promise<AuthResponse>

  Example

  const { data, error } = await auth.refreshSession()
  Copy

  See

  Refresh Token

setSession

• setSession(
      currentSession: { access_token: string; refresh_token: string },
  ): Promise<AuthResponse>

  Adopts an externally-provided session into the client.

  Decodes the access token to find its expiry; refreshes immediately when already expired, otherwise fetches the user info to round-trip the session. Persists the result and broadcasts SIGNED_IN. An invalid refresh or access token surfaces as error on the returned object.

  Parameters

  • currentSession: { access_token: string; refresh_token: string }

    Minimal session shape — an access token and a refresh token. Other fields are recomputed.

  Returns Promise<AuthResponse>

  Example

  // After receiving tokens from a custom server-side handoff
  await auth.setSession({ access_token, refresh_token })
  Copy

  See

  UserInfo

startAutoRefresh

• startAutoRefresh(): Promise<void>

  Starts an auto-refresh process in the background. The session is checked every few seconds. Close to the time of expiration a process is started to refresh the session. If refreshing fails it will be retried for as long as necessary.

  If autoRefreshToken is enabled in the client config you don't need to call this function, it will be called for you.

  On browsers the refresh process works only when the tab/window is in the foreground to conserve resources as well as prevent race conditions and flooding auth with requests. If you call this method any managed visibility change callback will be removed and you must manage visibility changes on your own.

  On non-browser platforms the refresh process works continuously in the background, which may not be desirable. You should hook into your platform's foreground indication mechanism and call these methods appropriately to conserve resources.

  Returns Promise<void>

  Example

  // React Native / Node: drive the refresh loop on focus events yourself
  appState.addEventListener('change', state => {
    if (state === 'active') auth.startAutoRefresh()
  })
  Copy

  See

  Refresh Token

changePassword

• changePassword(
      params: { email: string },
  ): Promise<{ data: unknown; error: AuthError | null }>

  Triggers a "change your password" email for a database-connection user.

  The current session is unaffected — the user clicks the link in the email and completes the reset on the tenant's hosted pages. The promise resolves once the email has been queued.

  Parameters

  • params: { email: string }

    The user's email address.

  Returns Promise<{ data: unknown; error: AuthError | null }>

  Example

  await auth.changePassword({ email: 'user@example.com' })
  Copy

  See

  Connections

signOut

• signOut(options?: SignOut): Promise<{ error: AuthError | null }>

  Signs the user out and clears the session from storage.

  In a browser context this removes the persisted session and broadcasts a SIGNED_OUT event to every tab listening on the same storageKey. The access token JWT itself remains valid until its exp — keep that expiry short.

  Scopes:

  • 'global' (default) — invalidate all refresh tokens for the user
  • 'local' — only clear this client's storage
  • 'others' — invalidate every refresh token except this device's; no SIGNED_OUT event is fired locally

  Parameters

  • options: SignOut = ...

  Returns Promise<{ error: AuthError | null }>

  Example

  await auth.signOut() // global — all sessions for this user
  await auth.signOut({ scope: 'local' }) // only this device
  Copy

  See

  Logout

initialize

• initialize(): Promise<InitializeResult>

  Initializes the client session either from the URL or from storage.

  Automatically called once from the constructor and idempotent — extra calls return the same in-flight promise. Call it explicitly when you need to await an OAuth, magic link, or password-recovery redirect to finish processing so you can surface any returned error.

  Returns Promise<InitializeResult>

  A promise that resolves to { error } — non-null when the URL carried a failure or storage was corrupt; never throws.

  Example

  const { error } = await auth.initialize()
  if (error) console.error('Auth redirect failed', error)
  Copy

  See

  Authorization Code with PKCE