Fan sign-in
The full OAuth path, session handling and account linking.
Quickstart has the minimum version. This page covers the parts you hit second.
How it works
Your app builds a sign-in URL and sends the fan to the FanBase OAuth proxy. The proxy runs the handshake with Discord, Google, X or Twitch. The fan approves. The proxy returns them to your callback with a one-time token. You exchange that token for a session.
The proxy exists so you never handle provider client secrets and never register your app with four different providers.
Providers
google, discord, twitter, twitch. Lowercase, exact.
Which ones you offer is your choice. Most gaming and esports partners lead with Discord because most quests involve a Discord account and it saves the fan a second linking step later.
Building the sign-in URL
import { buildOAuthProxyUrl, buildLoginUrl } from '@xborglabs/fanbase-react'
const proxyUrl = buildOAuthProxyUrl({
oauthProxyUrl: import.meta.env.VITE_FANBASE_OAUTH_PROXY_URL,
proxySecret: import.meta.env.VITE_FANBASE_OAUTH_PROXY_SECRET,
})Build this once. It resolves the secret against the proxy base, and the trailing slash on the base is load-bearing when the proxy sits on a path. Environment.
const loginUrl = buildLoginUrl({
oauthProxyUrl: proxyUrl,
provider: 'discord',
redirectUrl: 'https://yoursite.com/auth/callback?provider=discord',
})redirectUrl is absolute and has to be registered with the proxy. Local ports and preview deploys included. Send us every URL you need.
Carrying the provider through
The proxy returns to your callback with ?token= only. It does not tell you which provider was used, and the exchange needs it.
Two ways, and doing both costs nothing:
sessionStorage.setItem('fanbase.provider', provider)
const redirectUrl = new URL(import.meta.env.VITE_FANBASE_OAUTH_REDIRECT_URL)
redirectUrl.searchParams.set('provider', provider)The query param survives a new tab. sessionStorage survives a redirect chain that drops params. Between them you are covered.
The callback page
import { useEffect, useState } from 'react'
import { useFanbase, parseOAuthCallbackToken } from '@xborglabs/fanbase-react'
import { useNavigate } from 'react-router-dom'
export function AuthCallback() {
const { state, actions } = useFanbase()
const navigate = useNavigate()
const [error, setError] = useState(null)
useEffect(() => {
if (!state.ready) return
const token = parseOAuthCallbackToken(window.location.href)
if (!token) {
setError('No sign-in token found. Please try again.')
return
}
const provider =
new URLSearchParams(window.location.search).get('provider') ??
sessionStorage.getItem('fanbase.provider')
if (!provider) {
setError('Could not determine the sign-in method.')
return
}
actions
.loginWithToken({ provider, token })
.then(() => {
sessionStorage.removeItem('fanbase.provider')
navigate('/quests', { replace: true })
})
.catch(() => setError('Sign-in failed. Please try again.'))
}, [state.ready])
if (error) return <YourError message={error} onRetry={() => navigate('/')} />
return <YourSpinner label="Signing you in" />
}Three things this page gets right that a rushed version does not.
It waits for state.ready. The provider restores an existing session from your adapter on mount. Exchanging a token before that finishes leaves you in an inconsistent state. This is the single most common callback bug.
It handles a missing token. Fans land on callback URLs from history and bookmarks. Show something rather than hanging on a spinner.
It replaces the history entry. The token is single-use, so a back button that returns here would fail. replace: true removes it from history.
Under the hood the exchange is POST /v1/user/auth/{provider}/login.
Session state
const { state, actions } = useFanbase()
state.ready // provider has finished restoring
state.session // null, or { accessToken, refreshToken }Signed in means state.session is non-null with both tokens. The SDK attaches the access token as a Bearer header on every request. Nothing is stored in cookies, so no third-party cookie behaviour to work around.
Session adapter
Any object with get, set and clear. The SDK does not care where the session lives.
const session = {
get: () => JSON.parse(localStorage.getItem('fanbase.session') ?? 'null'),
set: (s) => localStorage.setItem('fanbase.session', JSON.stringify(s)),
clear: () => localStorage.removeItem('fanbase.session'),
}localStorage is the default for a browser SPA. If your security posture wants tokens out of JS-readable storage, write an adapter that talks to your own backend and keeps them in httpOnly cookies. Nothing else in your integration changes.
Signing out
actions.logout()Clears the adapter and the in-memory session. Local to your app; it does not sign the fan out of Discord.
Linking social accounts
Separate from sign-in. A fan signs in with Google and then needs a Discord account linked to complete a Discord quest. Same proxy round trip, different intent, and a few traps of its own, including a token that expires in five minutes. Linking accounts covers the whole flow.
Fan profile
Some quests are gated on what the fan has linked. To evaluate that, the machine needs the fan's linked accounts and wallets.
Linked accounts come from useLinkedSocials. Wallets come from the fan profile at GET /v1/user/profile:
import { useLinkedSocials } from '@xborglabs/fanbase-react'
const { data: socials = [] } = useLinkedSocials()
const { data: profile } = useQuery({
queryKey: ['fanbase', 'profile'],
queryFn: () => meta.http.get('/v1/user/profile'),
enabled: !!state.session,
})
const authProfile = { socials, wallets: profile?.wallets }Do not take the socials from the profile as well. The profile leaves out when each link expires and which Riot region an account is on, and without those the machine cannot tell an expired link from a working one. useLinkedSocials is the only read that has both.
meta.http from useFanbase() is the SDK's authenticated client, so the tenant header and Bearer token are handled.
Fetch these once after sign-in and hold them. Every quest detail view needs them and refetching per quest is wasted. Quest detail shows where they go.
Checklist
- Sign-in URL sends the fan to the provider's consent screen
- Callback exchanges the token with the same provider that started it
state.sessionhas both tokens- Refresh keeps the fan signed in
logout()clears it- Landing on the callback with no token shows a message, not a spinner
- Every redirect URL you use is registered, local ports included