One identity for
every app you build.

whyBuilt for your stack

FBID drops into anything — Next.js, plain HTML, mobile webviews, server-side. It speaks standard OAuth 2.0 + PKCE, so if you've shipped "Sign in with Google," you already know the shape.

01Quickstart

From zero to a working login in three steps.

npm install @flowbond/auth

import { FlowBond } from '@flowbond/auth'

const fb = new FlowBond({
  appId: 'app_live_xxx',
  redirectUri: 'https://yourapp.com/callback',
})

// open the FlowBond hub and return a verified user
const user = await fb.connect()

console.log(user.fbid, user.handle) // → "fb_a1b2…", "@steph"

02The Connect button

This is the entire user experience. Click it to preview the handoff your users will feel — open the hub, approve, return identified.

03Install & setup

Pick your environment. The SDK ships ESM, a React adapter, and a zero-dependency browser script.

npm install @flowbond/auth
# or: pnpm add @flowbond/auth · yarn add @flowbond/auth

import { FlowBondProvider } from '@flowbond/auth/react'

export default function App({ Component, pageProps }) {
  return (
    <FlowBondProvider appId="app_live_xxx">
      <Component {...pageProps} />
    </FlowBondProvider>
  )
}

<script type="module">
  import { FlowBond } from 'https://cdn.flowbond.app/auth/v1/flowbond.js'
  const fb = new FlowBond({ appId: 'app_live_xxx' })
</script>

04SDK reference

The full surface of @flowbond/auth. Same identity primitives in vanilla JS and React.

const fb = new FlowBond({ appId, redirectUri, scopes: ['identity', 'profile'] })

await fb.connect()            // open hub → returns User
await fb.getUser()            // current user or null
const t = await fb.getToken()    // access token for your API calls
fb.onAuthChange(user => {})   // subscribe to session changes
await fb.signOut()            // clear local session

// the User object you get back
{
  fbid: 'fb_a1b2c3',         // canonical, stable identity id
  handle: '@steph',
  displayName: 'Steph Ferrera',
  avatar: 'https://…',
  verified: true
}

import { useFlowBond, ConnectButton } from '@flowbond/auth/react'

function Profile() {
  const { user, loading, signOut } = useFlowBond()

  if (loading) return <Spinner/>
  if (!user) return <ConnectButton/>       // the drop-in button

  return <div>gm, {user.handle} <button onClick={signOut}>leave</button></div>
}

05REST API

Prefer to drive it yourself? Every SDK call maps to a documented endpoint. Base URL https://api.flowbond.app/v1.

Authorization flow (OAuth 2.0 + PKCE)

Identity

Example — exchange & fetch the user

curl https://api.flowbond.app/v1/identity/me \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# → { "fbid": "fb_a1b2c3", "handle": "@steph", "verified": true }

const res = await fetch('https://api.flowbond.app/v1/identity/me', {
  headers: { Authorization: `Bearer ${token}` }
})
const user = await res.json()

06Identity model

The mental model is small on purpose. There is one canonical id, and you map it onto your own data.

• FBID — a stable, canonical identity id (fb_…). One human, one FBID, forever. Use it as the foreign key in your tables.
• Profile — the portable, user-owned layer: handle, display name, avatar, verified status. Shared across the network.
• Session — a short-lived access token (+ refresh) scoped to your app and the scopes the user approved.
• Scopes — identity (the fbid) and profile (name/handle/avatar) today; more granular scopes are opt-in.

-- map FlowBond identity straight onto your rows
create table posts (
  id      uuid primary key default gen_random_uuid(),
  fbid    text not null,   -- ← FlowBond ID
  body    text,
  created timestamptz default now()
);

07Developer tools

Everything you need to build and debug. Spin up sandbox keys right here to try the flow before you register a production app.

Generate sandbox keys

# Click “Generate keys” to mint a throwaway sandbox app id + secret.

08Go to production

The short checklist before you flip to live keys.

• ✓Swap app_test_… for your app_live_… id and set live redirect URIs.
• ✓Keep the app secret server-side only; never ship it to the browser.
• ✓Verify tokens server-side with /identity/verify before trusting a session.
• ✓Store fbid as your user key and enforce it in Supabase RLS policies.
• ✓Handle onAuthChange so the UI reacts when a session ends or refreshes.