Fanvue API Documentation

@fanvue/builder-sdk is the TypeScript package for Fanvue apps. It runs OAuth and sessions, gives you a typed API client, verifies webhooks and talks to the Fanvue host from inside an iframe. Install it here, pick the entrypoint that matches where your code runs, then follow the guide for your app type. You need a registered app and its OAuth credentials from the Developer Area.

Install

Install the package once; every entrypoint ships in it. The Builder SDK guides use version 0.8.0.

npm install @fanvue/builder-sdk

The package declares two optional peer dependencies. Install only the ones your entrypoints need.

Peer dependency	Version	Needed by
`next`	`>=14.0.0`	`nextjs/off-platform`, `nextjs/embedded-app`
`react`	`>=18.0.0`	`react`

An API-only app installs neither. The package declares no Node version requirement.

Entrypoints

Each entrypoint is a separate import path. Pick the one for where the code runs and which app type you’re building.

Import path	Contents	Runtime	App type
`@fanvue/builder-sdk`	OAuth primitives, API client, webhook helpers, encryption, token store, contracts, logging	Any Node, edge or browser runtime	All. An API-only app uses only this entrypoint.
`@fanvue/builder-sdk/nextjs/off-platform`	Login, callback and logout route handlers, cookie session, `getAuthenticatedClient`	Next.js App Router	Off-platform
`@fanvue/builder-sdk/nextjs/embedded-app`	Session exchange, security headers, creator and fan session handlers, route guards, vault proxy, webhook receiver	Next.js App Router	On-platform
`@fanvue/builder-sdk/react`	`AuthProvider`, `useAuth`, `useEmbeddedAuth`, `useFanvueAnalytics`, `useDialog`	React 18 or later in the browser	On-platform
`@fanvue/builder-sdk/bridge`	`connectFanvueBridge` and the bridge protocol schemas, for surfaces without React	Browser, inside a Fanvue iframe	On-platform

Environment variables

The SDK reads two sets of variables, and an app can use either or both. The OAUTH_* set feeds createConfig in both Next.js entrypoints. The FANVUE_* set feeds fanvueEnv(), the session handlers and the readiness checks.

Variable	Required	Read by
`OAUTH_CLIENT_ID`	Yes	`createConfig`, `createConfigSafe`
`OAUTH_CLIENT_SECRET`	Yes	`createConfig`, `createConfigSafe`
`OAUTH_REDIRECT_URI`	Yes	`createConfig`, `createConfigSafe`
`SESSION_SECRET`	Yes	`createConfig`, `createConfigSafe`. Use at least 32 characters. `createConfig` accepts any length, but `createAppSessions` and `requireMachineAuth` refuse shorter secrets.
`OAUTH_ISSUER_BASE_URL`	No	`createConfig`. Default `https://auth.fanvue.com`.
`API_BASE_URL`	No	`createConfig`. Default `https://api.fanvue.com`. Must be a `fanvue.com` host.
`OAUTH_SCOPES`	No	`createConfig`. Space-separated scopes added to the defaults.
`OAUTH_RESPONSE_MODE`	No	`createConfig`. Set `form_post` to receive the callback as a `POST`.
`OAUTH_PROMPT`	No	`createConfig`. Forwarded as the `prompt` parameter of the authorisation request.
`BASE_URL`	No	`createConfig`. Public origin used to build redirect targets.
`SESSION_COOKIE_NAME`	No	`createConfig`. Default `fanvue_session`.
`FANVUE_PLATFORM_URL`	No	`createConfig` from `nextjs/embedded-app`. Default `https://www.fanvue.com`.
`FANVUE_APP_UUID`	For on-platform apps with a token store	`fanvueEnv()`, `isFanvueConfigured`, `configurationReadiness`
`FANVUE_CLIENT_ID`	For on-platform apps with a token store	`fanvueEnv()`, `isFanvueConfigured`, `configurationReadiness`
`FANVUE_CLIENT_SECRET`	For on-platform apps with a token store	`fanvueEnv()`, `isFanvueConfigured`, `configurationReadiness`
`FANVUE_OAUTH_REDIRECT_URI`	For on-platform apps with a token store	`fanvueEnv()`, `isFanvueConfigured`, `configurationReadiness`
`FANVUE_API_BASE_URL`	No	`fanvueEnv()`. Default `https://api.fanvue.com`. Blank means default.
`FANVUE_AUTH_BASE_URL`	No	`fanvueEnv()`. Default `https://auth.fanvue.com`. Blank means default.
`FANVUE_WEB_ORIGIN`	No	`fanvueEnv()`. Default `https://www.fanvue.com`. Must parse as a URL.
`FANVUE_API_VERSION`	No	`fanvueEnv()`. Default `2025-06-26`. Pass it to `createFanvueClient` as `apiVersion`.
`FANVUE_EXPERIENCE_URL_TEMPLATE`	No	`fanvueEnv()`, `experienceShareUrl`. Empty means derive the URL.
`FANVUE_WEBHOOK_SIGNATURE_PROFILE`	For webhook receivers	`webhookSignatureContractFromEnv`. Set `fanvue-v0`.
`FANVUE_APP_BASE_URL` or `APP_BASE_URL`	For readiness checks	`configurationReadiness`. Must be an `https` origin.

createConfig throws when a required OAUTH_* variable is missing. createConfigSafe returns { ok: false, missing } instead, so a route can answer 503 rather than crash.

Defaults

When you set nothing, the SDK falls back to these constants, exported from the core entrypoint.

Constant	Value
`DEFAULT_SCOPES`	`openid offline_access offline`. Always requested; `OAUTH_SCOPES` adds to this set.
`DEFAULT_ISSUER_URL`	`https://auth.fanvue.com`
`DEFAULT_API_BASE_URL`	`https://api.fanvue.com`
`DEFAULT_PLATFORM_URL`	`https://www.fanvue.com`
`API_VERSION`	`2025-06-26`. Sent as `X-Fanvue-API-Version` on every client request.

The client pins X-Fanvue-API-Version to API_VERSION unless you pass apiVersion in createFanvueClient options.

Result type

Every network call in the SDK returns a Result instead of throwing. A Result is either ok, holding a value, or err, holding an error, so check isOk() or isErr() before you read either field. Errors come from four unions. Each arm carries a code string you can branch on.

Union	Arms	Returned by
`OAuthError`	`TOKEN_EXCHANGE_FAILED`, `TOKEN_REFRESH_FAILED`, `OAUTH_JSON_PARSE_ERROR`, `OAUTH_VALIDATION_ERROR`	`exchangeCodeForToken`, `refreshAccessToken`
`ApiError`	`API_REQUEST_FAILED`, `API_TIMEOUT`, `API_ERROR_RESPONSE`, `API_JSON_PARSE_ERROR`, `API_VALIDATION_ERROR`	Every `createFanvueClient` method
`SessionVerifyError`	`JWT_VERIFY_FAILED`, `SESSION_VALIDATION_ERROR`	`verifySessionJwt`
`EmbeddedAuthError`	`SESSION_TOKEN_REJECTED`, `CONSENT_REQUIRED`, `AUTHORIZE_ON_BEHALF_FAILED`, `AUTHORIZE_STATE_MISMATCH`, `EMBEDDED_JSON_PARSE_ERROR`, `EMBEDDED_VALIDATION_ERROR`	`exchangeSessionToken`, `requestAuthorizationCodeOnBehalf`

The API_ERROR_RESPONSE arm carries statusCode, the platform’s machine-readable reason when one was sent, and retryAfterSeconds parsed from Retry-After or X-RateLimit-Reset. Its message is upstream text, so log it but never render it to a user.

import { createFanvueClient } from "@fanvue/builder-sdk";

const client = createFanvueClient(accessToken, null);
const result = await client.getCurrentUser();

if (result.isErr()) {
  if (result.error.code === "API_ERROR_RESPONSE" && result.error.statusCode === 429) {
    console.warn("rate limited, retry after", result.error.retryAfterSeconds);
  }
  return null;
}

return result.value.handle;

Configuration and guard helpers never touch the network, so they return plain discriminated unions instead, such as createConfigSafe ({ ok, config | missing }), the route guards ({ ok, session | response }) and requireMachineAuth (status).

Which guide next

Off-platform sign-in

Route handlers and a cookie session for a Next.js app creators sign in to.

Run inside Fanvue

Session exchange, headers and React hooks for an on-platform creator surface.

API client

Typed namespaces for chats, checkout, experiences, subscribers, vault and webhooks.

Webhooks

The receiver route, signature verification and subscription lifecycle.

Host bridge

Analytics events and host-rendered dialogs from inside the iframe.

Storage and security

Encrypted token storage, app sessions, machine auth and log scrubbing.

Overview

Builder SDK

Fan experiences

App Manifest

Submit and review

Builder SDK overview

Install

Entrypoints

Environment variables

Defaults

Result type

Which guide next

Off-platform sign-in

Run inside Fanvue

API client

Webhooks

Host bridge

Storage and security

See also

​Install

​Entrypoints

​Environment variables

​Defaults

​Result type

​Which guide next

Off-platform sign-in

Run inside Fanvue

API client

Webhooks

Host bridge

Storage and security

​See also

Install

Entrypoints

Environment variables

Defaults

Result type

Which guide next

See also