> ## 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.

# Fanvue OAuth Quick Start (Next.js App Router)

> Build a working Next.js app with Login with Fanvue using OAuth, starting from the official App Starter.

In a few minutes you’ll have a working Next.js app where users can “Login with Fanvue” using OAuth. We’ll start from the official Fanvue App Starter and run locally with pnpm.

<Note>Adding OAuth to an existing app instead of starting fresh? See the [OAuth Implementation Guide](/docs/authentication/implementation-guide) for the framework-agnostic steps.</Note>

### What you’ll build

* **Secure OAuth login** with Fanvue
* **Session-backed** current-user page after sign-in
* **Production-ready** settings you can deploy anywhere

<Note>
  ##### Prerequisites

  * A Fanvue **creator account with KYC completed**, only creators can access the Builder area. Fans cannot create or publish apps.
  * Node.js 18 or later
  * pnpm installed
  * Access to the Fanvue Developer area to create an app (Client ID/Secret)
</Note>

## 1) Bootstrap from the Fanvue App Starter

Use the template repository: [Fanvue App Starter](https://github.com/fanvue/fanvue-app-starter)

Pick one of these ways to start from the template:

1. **Use this template on GitHub**

   * Open: [Fanvue App Starter](https://github.com/fanvue/fanvue-app-starter)
   * Click "Use this template" → "Create a new repository"
   * Clone your new repository locally

2. **Scaffold via 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>Always use pnpm for install, dev, and build commands.</Warning>

## 2) Set up local HTTPS proxy

OAuth requires HTTPS redirect URIs, even in local development. We'll use `mkcert` and `local-ssl-proxy` to enable HTTPS locally.

<Tip>
  ##### Alternative: portless

  Prefer a single tool over the `mkcert` + `local-ssl-proxy` + hosts-file steps below? [portless](https://github.com/vercel-labs/portless) generates the HTTPS proxy for you: 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   # → https://my-fanvue-app.localhost
  ```

  If you go this route, set your redirect URI and `OAUTH_REDIRECT_URI` to match the URL portless serves (for example `https://my-fanvue-app.localhost/api/oauth/callback`, with no `:3001` port), and skip the `mkcert`/`local-ssl-proxy` steps in this section.
</Tip>

### Install mkcert

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

### Generate SSL certificates

Replace `my-fanvue-app` with your app name:

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

This creates two files: `my-fanvue-app.dev.pem` and `my-fanvue-app.dev-key.pem`

### Update hosts file

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

<Note>
  You'll run the proxy later after configuring environment variables. The proxy will forward HTTPS
  traffic from port 3001 to your Next.js dev server on port 3000.
</Note>

## 3) Create your Fanvue OAuth app

In the Fanvue Developer area, create a new App to obtain credentials:

* **Client ID** and **Client Secret**
* **Redirect URI**
  * Development: `https://my-fanvue-app.dev:3001/api/oauth/callback` (replace `my-fanvue-app` with your app name)
  * Production: `https://YOUR_DOMAIN/api/oauth/callback`
* **Scopes**
  * For the starter, use: `read:self`
  * The starter automatically includes required system scopes (`openid`, `offline_access`, `offline`) in addition to what you set in `OAUTH_SCOPES`

## 4) Configure environment variables

Create `.env.local` in the project root and set the following (replace `my-fanvue-app` with your app name):

```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=use-a-random-16-char-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
```

<Warning>
  * Never commit `.env.local` to version control - Ensure `OAUTH_SCOPES` exactly matches what you
    configured in the Fanvue developer UI
</Warning>

## 5) Install and run locally

First, install dependencies and start the Next.js dev server:

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

In a **separate terminal**, start the local SSL proxy (replace `my-fanvue-app` with your app name):

```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` (replace with your app name) and click "Login with Fanvue". After authorizing, you'll be redirected back and see your current user JSON rendered by the app.

## 6) How it works (at a glance)

* Next.js App Router with an OAuth callback at `/api/oauth/callback`
* Session cookie (`SESSION_COOKIE_NAME`) signed with `SESSION_SECRET`
* Server-side calls to `API_BASE_URL` using the authenticated session
* Local SSL proxy forwards HTTPS requests to the Next.js dev server

## 7) Production deployment

* Set the same environment variables in your hosting provider
* In the Fanvue developer UI, add the production Redirect URI: `https://YOUR_DOMAIN/api/oauth/callback`
* Build and run

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

### Recommended services

* Vercel for hosting
* Supabase if you also need a database

## Troubleshooting

* **Invalid redirect URI**: The value in the Fanvue developer UI must exactly match `OAUTH_REDIRECT_URI` (including the HTTPS protocol and port 3001)
* **Scope mismatch**: `OAUTH_SCOPES` must exactly match the scopes selected in the Fanvue developer UI (starter uses `read:self`)
* **Missing session secret**: Set `SESSION_SECRET` to a random string with at least 16 characters
* **Certificate errors in browser**: Run `mkcert -install` to install the local CA certificate
* **Cannot reach app at .dev domain**: Verify the hosts file entry with `cat /etc/hosts | grep my-fanvue-app.dev`
* **Proxy connection refused**: Ensure the Next.js dev server is running on port 3000 before starting the proxy
* **Port already in use**: If port 3000 or 3001 is in use, stop other services or use different ports (update proxy and redirect URI accordingly)
* **Blank page after login**: Open browser DevTools and your terminal; ensure all env vars are set, the proxy is running, and the callback route is reachable

## Where to customize in the starter

* 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

## Next steps

* Add additional scopes in both the Fanvue developer UI and `OAUTH_SCOPES`
* Call other endpoints (e.g., chats, followers) from your server routes
* Protect pages with middleware that checks the session
* **Test your app safely**: Set up a [test creator account](/docs/introduction/testing-your-app) to avoid affecting your real profile

Resources:

* Fanvue App Starter: [github.com/fanvue/fanvue-app-starter](https://github.com/fanvue/fanvue-app-starter)