Getting started

Environment

The eight config values, with beta defaults you can paste.

Eight values. Your FanBase contact provides all of them for your community. The examples below use Vite's VITE_ prefix; rename for Next.js (NEXT_PUBLIC_) or your own framework.

The values

VariableWhat it is
VITE_FANBASE_TENANTYour tenant host. Sent as the xb-tenant header on every API request.
VITE_FANBASE_COMMUNITY_SLUGYour community's slug. Community identifier only, never an auth path or a provider name.
VITE_FANBASE_APP_IDIdentifies this specific app or environment within your community.
VITE_FANBASE_GAMER_BASE_URLAPI base URL. Beta and production differ.
VITE_FANBASE_LOCALEDisplay language. Defaults to en.
VITE_FANBASE_OAUTH_PROXY_URLThe OAuth proxy that handles the provider handshake.
VITE_FANBASE_OAUTH_PROXY_SECRETRouting key for your community on the proxy. See the note below.
VITE_FANBASE_OAUTH_REDIRECT_URLAbsolute URL of your callback page. Has to be registered with the proxy.

Beta defaults

Working values against beta, for a local Vite app on port 5173:

VITE_FANBASE_TENANT=xbg-beta.apps.gamerbase.gg
VITE_FANBASE_COMMUNITY_SLUG=xbg
VITE_FANBASE_APP_ID=local_5173_beta
VITE_FANBASE_GAMER_BASE_URL=https://api-beta.gamerbase.gg
VITE_FANBASE_LOCALE=en

# OAuth proxy
VITE_FANBASE_OAUTH_PROXY_URL=https://oauth-beta.gamerbase.gg/
VITE_FANBASE_OAUTH_PROXY_SECRET=local_5173_beta
VITE_FANBASE_OAUTH_REDIRECT_URL=http://localhost:5173/auth/callback

Paste that and the app runs. Swap in your own values when you move off the shared beta community.

The tenant header

VITE_FANBASE_TENANT becomes the xb-tenant header, and it goes out on every request the SDK makes.

It scopes the data you get back. Your tenant's quests, your tenant's rewards. Getting it right matters more than it looks:

Header valueWhat happens
Your correct tenantYour community's data
A wrong value, including a placeholder400 generic_client_error on every endpoint
Header absent entirely200 with a different, unscoped dataset

The silent one

Header absent returns a 200 with someone else's data. Nothing errors and the app renders, so if your quest list looks plausible but does not match your admin panel, check this first.

That last row is the one to watch. Nothing errors, the app renders, and the content belongs to someone else. If your quest list looks plausible but does not match your admin panel, check this header first.

The trailing slash on the proxy URL

VITE_FANBASE_OAUTH_PROXY_URL is resolved as a URL base, so a trailing slash changes the result when the proxy is mounted on a path:

ValueResolves to
https://oauth.example.com/https://oauth.example.com/SECRET
https://oauth.example.com/fanbase/https://oauth.example.com/fanbase/SECRET
https://oauth.example.com/fanbasehttps://oauth.example.com/SECRET

Include the trailing slash. If you are on a root-mounted proxy it makes no difference, and if you are ever moved to a path-mounted one it saves an afternoon.

About the proxy secret

Despite the name, this is a routing key, not a credential. It is the path segment that tells the proxy which configuration a sign-in belongs to: which providers are enabled, and which callback URL is allowed.

It compiles into your public bundle and shows up in the sign-in URL. That is expected. A production build of your app contains it.

Your security reviewer will stop here, so what it cannot do:

  • It does not authorise a request, carry an identity, or read anything. It selects a configuration.
  • The callback URL lives on our side. The proxy only returns a fan to a URL registered against that configuration, so the key on its own cannot send a sign-in anywhere else.
  • Rotating it is a support request, not an incident.

Authority sits in the token instead. The proxy returns an encrypted token, your app exchanges it for a session, and after that it is a JWT in your session adapter sent as a Bearer header. None of that goes in a URL.

One scoping caveat. This key is configured per proxy entry, not per community, and one entry can cover several surfaces in the same organisation. If you run several communities that need isolating at sign-in, check the arrangement with your FanBase contact.

Registering your redirect

VITE_FANBASE_OAUTH_REDIRECT_URL has to be registered with the proxy before sign-in works. Send us every URL you need, including local development ports and preview deployments. An unregistered redirect fails at the provider handshake.

On this page