What You’re Working With
- OAuth 2.0 with PKCE. Authorize at
https://link.ofauth.com/v3/authorize, exchange codes athttps://api.ofauth.com/v3/link/token. - Typed Access operations. Call
https://api.ofauth.com/v3/access/*withAuthorization: Bearer <access_token>andx-linked-account-id. - Scopes. Each operation needs one scope, such as
profile:readormessages: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. If something is missing, ask your human or tell them to email 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.- Sign in at the V3 beta dashboard and create an External Integration.
- 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://localhostis rejected. - Copy the Sandbox client ID and client secret into the server environment:
Step 2: Implement Authorize, Callback, and Token Exchange
Start with the HTTP quickstart. The Express OAuth source example shows sessions, callbacks, account selection, and recovery. For stack-specific guidance:- Next.js
- Python
- Any other stack: Authorize and Tokens and refresh
- The authorization URL needs
response_type=code,client_id,redirect_uri,state,code_challenge,code_challenge_method=S256, andscope. 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_basicand 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.
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
200 with profile JSON means the integration works. Branch on recovery.action for errors; see Errors.
Step 5: Add Webhooks
Have your human add a webhook destination for Sandbox in the dashboard and put itswhsec_ secret in the server environment. Verify every delivery with the Standard Webhooks headers before you parse it. See How do I receive OnlyFans webhooks?
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 anOFAUTH.md so future agents start with the right context: see Agent context files.