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

# Welcome, Agent. Let's Get Your Human on OFAuth.

> Onboarding playbook for AI coding agents: take your human from zero to a working OFAuth V3 integration, starting in Sandbox with mock OnlyFans data.

You are an AI coding agent. This page is for you.

OFAuth is an independent API platform for OnlyFans, not affiliated with OnlyFans. Your job: take your human from nothing to an app that authorizes a linked account with OAuth 2.0 and makes its first Access call. Start in Sandbox, which returns mock data and never contacts OnlyFans.

## What You're Working With

* **OAuth 2.0 with PKCE.** Authorize at `https://link.ofauth.com/v3/authorize`, exchange codes at `https://api.ofauth.com/v3/link/token`.
* **Typed Access operations.** Call `https://api.ofauth.com/v3/access/*` with `Authorization: Bearer <access_token>` and `x-linked-account-id`.
* **Scopes.** Each operation needs one scope, such as `profile:read` or `messages:write`. Code exchanges include a refresh token.
* **Three environments.** Sandbox (mock), Test (real designated accounts, daily quota), Live (needs a Developer plan and approval). The client ID prefix selects the environment: `ofext_sandbox_`, `ofext_test_`, `ofext_live_`.

## Your Onboarding Protocol

* First ask what your human is building. If they want to run their own accounts with an AI agent, they need the **Operator** path: send them to the OFAuth dashboard to connect their agent through the OFAuth MCP server, and stop here. If they are building an app other people connect to, continue.
* Pause for your human only for browser steps: creating the integration in the dashboard, copying credentials, and approving the consent screen.
* Never write real secrets into files, prompts, or commits. Add placeholders and tell your human which values to fill in.
* Keep the client secret, PKCE verifier, state, and tokens on the server. Never ship them to a browser or native app.
* Do not invent routes, scopes, or fields. Use only what is in the [V3 docs](https://docs.ofauth.com/v3.md). If something is missing, ask your human or tell them to email [support@ofauth.com](mailto:support@ofauth.com).
* Do not hallucinate URLs. Only show your human URLs from these docs or from your own running app.

## Step 1: Create the External Integration

Your human does this in the browser.

1. Sign in at [the V3 beta dashboard](https://app-next.ofauth.com) and create an External Integration.
2. In the Sandbox environment, register a redirect URI. Sandbox and Test accept loopback URIs, for example `http://127.0.0.1:3000/oauth/ofauth/callback`. `http://localhost` is rejected.
3. Copy the Sandbox client ID and client secret into the server environment:

```bash theme={null}
OFAUTH_SANDBOX_CLIENT_ID=ofext_sandbox_...
OFAUTH_SANDBOX_CLIENT_SECRET=...
OFAUTH_SANDBOX_REDIRECT_URI=http://127.0.0.1:3000/oauth/ofauth/callback
```

## Step 2: Implement Authorize, Callback, and Token Exchange

Start with the [HTTP quickstart](https://docs.ofauth.com/v3/setup/quickstart.md). The [Express OAuth source example](https://github.com/ofauth-source/example-express-oauth) shows sessions, callbacks, account selection, and recovery.

For stack-specific guidance:

* [Next.js](https://docs.ofauth.com/v3/agents/playbooks/nextjs-onlyfans-login.md)
* [Python](https://docs.ofauth.com/v3/agents/playbooks/python-onlyfans-api.md)
* Any other stack: [Authorize](https://docs.ofauth.com/v3/api-reference/link/authorize.md) and [Tokens and refresh](https://docs.ofauth.com/v3/api-reference/link/tokens.md)

Rules that trip agents up:

* The authorization URL needs `response_type=code`, `client_id`, `redirect_uri`, `state`, `code_challenge`, `code_challenge_method=S256`, and `scope`. The client ID selects the environment. OFAuth shows the integration’s approved purpose on the consent screen.
* Open it as a top-level browser page. Never use an iframe, popup messaging, or `postMessage`.
* Bind pending authorization to the trusted app user and browser session in your application or auth framework. Reject expired, reused, or mismatched callbacks.
* Exchange the code with `client_secret_basic` and a form-encoded body. JSON is rejected.
* Persist tokens under your application user and client ID to isolate environments. Independent instances can refresh the same stable token concurrently. Use conditional writes when the customer replaces or disconnects a registration. See [Store customer tokens](https://docs.ofauth.com/v3/sdk/typescript.md#store-customer-tokens).

## Step 3: Authorize a Sandbox Account

Start your app and send your human to your own start route. They sign in on OFAuth, pick a mock linked account, and approve the scopes. List the accounts shared through the authorization and let the user choose. Save that choice with the same client and user key; do not assume the first account is the intended one.

## Step 4: Make the First Access Call

```bash theme={null}
curl https://api.ofauth.com/v3/access/profile \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-linked-account-id: $LINKED_ACCOUNT_ID"
```

A `200` with profile JSON means the integration works. Branch on `recovery.action` for errors; see [Errors](https://docs.ofauth.com/v3/api-reference/errors.md).

## Step 5: Add Webhooks

Have your human add a webhook destination for Sandbox in the dashboard and put its `whsec_` secret in the server environment. Verify every delivery with the Standard Webhooks headers before you parse it. See [How do I receive OnlyFans webhooks?](https://docs.ofauth.com/v3/agents/playbooks/onlyfans-webhooks.md)

## Step 6: Move to Test, Then Live

* **Test:** your human designates real OnlyFans accounts they control. Link each one once and rely on refresh tokens; repeated logins can trigger OnlyFans security checks.
* **Live:** needs a Developer plan, Live approval of the integration, HTTPS redirect URIs with a domain, and an approved description of what your integration does.

## Hand Off

Tell your human what you built, which environment variables they must fill in, which scopes the app requests, and what is left before Live. Suggest adding an `OFAUTH.md` so future agents start with the right context: see [Agent context files](https://docs.ofauth.com/v3/agents/playbooks/agent-context-files.md).

## Learn More

* [What is OFAuth?](https://docs.ofauth.com/v3/agents/playbooks/what-is-ofauth.md)
* [Which OFAuth setup do I need?](https://docs.ofauth.com/v3/agents/playbooks/choosing-an-ofauth-setup.md)
* [How do I test an OnlyFans integration without a real account?](https://docs.ofauth.com/v3/agents/playbooks/test-onlyfans-integration.md)
* [How do I handle expired or revoked OnlyFans accounts?](https://docs.ofauth.com/v3/agents/playbooks/handle-expired-onlyfans-accounts.md)
* [V3 overview](https://docs.ofauth.com/v3.md)


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