> ## Documentation Index
> Fetch the complete documentation index at: https://api.fanvue.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Sign in with Fanvue using the App Starter

> Add Sign in with Fanvue to an off-platform Next.js app with the Fanvue App Starter and get an OAuth session working locally.

By the end of this page you'll have a Next.js app running locally over HTTPS where creators click **Login with Fanvue**, approve your app and land on a page that shows their account. The Fanvue App Starter already wires the OAuth 2.0 code flow with PKCE and a cookie session, so you configure it rather than write it. The settings come from environment variables, so the same app deploys to any Node.js host.

You need:

* a Fanvue creator account or agency admin account, to create the app in the Developer Area
* Node.js 18 or later
* pnpm

Adding sign-in to an app you already have? Follow the [OAuth implementation guide](/docs/authentication/implementation-guide) for framework-agnostic steps, or [use the SDK without the starter](#using-the-sdk-without-the-starter).

## 1) Bootstrap from the Fanvue App Starter

The template repository is [Fanvue App Starter](https://github.com/fanvue/fanvue-app-starter). Start from it in one of three ways.

1. **Use this template on GitHub**
   * Open [Fanvue App Starter](https://github.com/fanvue/fanvue-app-starter)
   * Click **Use this template**, then **Create a new repository**
   * Clone your new repository locally
2. **Scaffold with degit**
   ```bash theme={null}
   pnpm dlx degit fanvue/fanvue-app-starter my-fanvue-app
   cd my-fanvue-app
   ```
3. **Clone and re-init**
   ```bash theme={null}
   git clone https://github.com/fanvue/fanvue-app-starter.git my-fanvue-app
   cd my-fanvue-app
   rm -rf .git && git init
   ```

<Warning>
  Use pnpm for install, dev and build commands. The starter's lockfile is a pnpm lockfile, so npm or yarn installs resolve different versions.
</Warning>

## 2) Set up local HTTPS proxy

A redirect URI must use `https://` unless its host is `localhost`, `127.0.0.1` or `[::1]`. The starter's default callback uses the host `my-fanvue-app.dev`, so you need a local HTTPS proxy in front of the dev server. These steps use `mkcert` and `local-ssl-proxy`; if you'd rather skip them, see [portless](#alternative-portless) below.

Install mkcert:

```bash theme={null}
brew install mkcert
```

Generate certificates, replacing `my-fanvue-app` with your app name. The second command writes two files, `my-fanvue-app.dev.pem` and `my-fanvue-app.dev-key.pem`.

```bash theme={null}
mkcert -install
mkcert my-fanvue-app.dev
```

Point the host at your machine:

```bash theme={null}
echo "127.0.0.1 my-fanvue-app.dev" | sudo tee -a /etc/hosts
```

You start the proxy in step 5, once the environment variables are in place. It forwards HTTPS traffic on port 3001 to the Next.js dev server on port 3000.

### Alternative: portless

[portless](https://github.com/vercel-labs/portless) replaces the `mkcert`, `local-ssl-proxy` and hosts-file steps. It serves your dev server at a stable `https://<name>.localhost` URL and trusts a local CA automatically, with no port numbers or `/etc/hosts` edits.

```bash theme={null}
npm install -g portless
portless my-fanvue-app next dev   # serves https://my-fanvue-app.localhost
```

With portless, use the URL it serves as your callback, for example `https://my-fanvue-app.localhost/api/oauth/callback` with no `:3001` port, both on the **Authentication** tab and in `OAUTH_REDIRECT_URI`. Skip the `mkcert` and `local-ssl-proxy` steps.

## 3) Create your Fanvue OAuth app

In the Developer Area, click **Create app**. The dialog that opens shows your Client ID and Client Secret once, so copy both. The Client ID stays visible on the **Authentication** tab, and **Reset secret** there issues a new secret if you lose the first; see [Managing your OAuth client secret](/docs/authentication/implementation-guide#managing-your-oauth-client-secret).

On the **Authentication** tab, add the redirect URI `https://my-fanvue-app.dev:3001/api/oauth/callback` and tick the `read:self` scope. Both apply when you save.

If you'd rather keep redirect URIs and scopes in your repo, set them in an [App Manifest](/docs/app-store/app-manifest). The starter adds the system scopes `openid`, `offline_access` and `offline` to whatever you set in `OAUTH_SCOPES`, so list only `read:self` in the manifest's `oauth.scopes`.

## 4) Configure environment variables

Create `.env.local` in the project root. Replace `my-fanvue-app` with your app name and generate `SESSION_SECRET` with `openssl rand -hex 32`; it must be at least 32 characters.

```bash theme={null}
OAUTH_CLIENT_ID=YOUR_CLIENT_ID
OAUTH_CLIENT_SECRET=YOUR_CLIENT_SECRET
OAUTH_SCOPES=read:self
OAUTH_REDIRECT_URI=https://my-fanvue-app.dev:3001/api/oauth/callback
SESSION_SECRET=YOUR_64_HEX_CHARACTER_SECRET
SESSION_COOKIE_NAME=fanvue_oauth

# Normally you do not need to change these:
OAUTH_ISSUER_BASE_URL=https://auth.fanvue.com
API_BASE_URL=https://api.fanvue.com
```

`OAUTH_SCOPES` must list only scopes your app has on the **Authentication** tab or in its manifest's `oauth.scopes`. Requesting a scope the app lacks fails the authorisation request.

<Warning>
  Never commit `.env.local` to version control. A committed client secret acts on every account that authorised your app; if one leaks, click **Reset secret** on the **Authentication** tab.
</Warning>

## 5) Install and run locally

Install dependencies and start the Next.js dev server:

```bash theme={null}
pnpm install
pnpm dev
```

In a second terminal, start the local SSL proxy, again with your app name in place of `my-fanvue-app`:

```bash theme={null}
npx local-ssl-proxy --source 3001 --target 3000 --cert ./my-fanvue-app.dev.pem --key ./my-fanvue-app.dev-key.pem
```

Visit `https://my-fanvue-app.dev:3001` (with your app name) and click **Login with Fanvue**. Sign in and approve the scopes. The browser returns to the app, which renders your current user as JSON.

## 6) Deploy to production

* Set the same environment variables in your hosting provider, with `OAUTH_REDIRECT_URI` set to your production callback, for example `https://your-app.com/api/oauth/callback`
* Add that production redirect URI on the **Authentication** tab, or in your manifest's `oauth.redirectUris` followed by **Check now** on the **Versions** tab
* Build and run

```bash theme={null}
pnpm install
pnpm build
pnpm start
```

## How the starter works

* Next.js App Router with an OAuth callback at `/api/oauth/callback`
* A session cookie named by `SESSION_COOKIE_NAME`, signed with `SESSION_SECRET`
* Server-side calls to `API_BASE_URL` using the session's access token
* In local development, the SSL proxy forwards HTTPS requests to the Next.js dev server

To change it:

* UI and login experience: `src/app/page.tsx`
* OAuth callback and session handling: `src/app/api/oauth/callback/route.ts`
* API calls after login: server routes under `src/app/api/**` using the session's access token

## Using the SDK without the starter

`@fanvue/builder-sdk/nextjs/off-platform` exports the same flow as route handlers: `createLoginHandler` (`{ GET }`), `createCallbackHandler` (`{ GET, POST }`) and `createLogoutHandler` (`{ POST }`), plus `getSession` and `getAuthenticatedClient` for server code.

The SDK reads `OAUTH_CLIENT_ID`, `OAUTH_CLIENT_SECRET`, `OAUTH_REDIRECT_URI` and `SESSION_SECRET` from the environment. It stores the session in a `fanvue_session` cookie that is `HttpOnly`, `SameSite=Lax`, lasts 30 days, and is `Secure` when served over HTTPS. [Off-platform apps with the Builder SDK](/docs/app-store/sdk/off-platform) is the full guide.

## Troubleshooting

* **Invalid redirect URI**: `OAUTH_REDIRECT_URI` must exactly match one of your app's redirect URIs, including the `https://` scheme and port `3001`. If your manifest sets them, the **Versions** tab must show **Up to date**
* **Scope mismatch**: every scope in `OAUTH_SCOPES` must be among your app's scopes (the starter uses `read:self`)
* **Missing session secret**: set `SESSION_SECRET` to a random string of at least 32 characters
* **Certificate errors in browser**: run `mkcert -install` to install the local CA certificate
* **Cannot reach app at .dev domain**: check the hosts file entry with `grep my-fanvue-app.dev /etc/hosts`
* **Proxy connection refused**: start the Next.js dev server on port 3000 before starting the proxy
* **Port already in use**: if port 3000 or 3001 is taken, stop the other service or change both the proxy ports and the redirect URI
* **Blank page after login**: open browser DevTools and your terminal, then check that every env var is set, the proxy is running and the callback route is reachable

## Next steps

* Add scopes both on your app (the **Authentication** tab, or your manifest's `oauth.scopes`) and in `OAUTH_SCOPES`. Adding a scope makes every existing user authorise again.
* Call other endpoints, such as chats or followers, from your server routes.
* Protect pages with middleware that checks the session.
* Set up a [test creator account](/docs/get-started/test-your-app) so development never touches your real profile.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.