Hosted Mode - Link API

Overview

Hosted Mode provides the simplest integration path for OnlyFans authentication. Users are redirected to OFAuth’s secure authentication pages, reducing your security burden while providing a seamless authentication experience.

Prefer a popup experience? Use our Link Embed Library to keep users in your app rather than redirecting them away from your site.

How It Works

Initialize: Create a link session with your redirect URL
Redirect/Popup: Send users to OFAuth’s secure authentication page
Authentication: Users complete authentication on OFAuth’s pages
Return: Users are redirected back to your URL with status and connection details
Process: Handle the query params to complete the flow

Integration Options

Hosted Mode offers two integration approaches to fit your application’s user experience:

Redirect Integration

Traditional Flow - Redirect users to OFAuth’s authentication pages. Perfect for web applications and simple mobile integrations.

Popup/Embed Integration

Seamless UX - Use our Embed SDK to display authentication in a popup or iframe. Keeps users in your application throughout the flow.

Base URL

https://api.ofauth.com/v2/link

Authentication

All requests require your API key header:

apikey: YOUR_API_KEY

Core Endpoints

Initialize Hosted Session

Create a new hosted authentication session.

Show POST /v2/link/init

POST /v2/link/init

Headers:

apikey: Your API key (required)
Content-Type: application/json

Request Body:

{
	"redirectUrl": "https://yourapp.com/callback",
	"clientReferenceId": "user_123",
	"connectionId": "conn_existing_123"
}

Parameters:

Parameter	Type	Required	Description
`redirectUrl`	string	No	URL to redirect to after completion. If omitted, uses first Allowed Redirect URI.
`clientReferenceId`	string	No	Your internal user identifier for webhook correlation
`connectionId`	string	No	Existing connection ID to reconnect to

Configure your Allowed Redirect URIs in the OFAuth dashboard under Developers → API. If you don’t specify a redirectUrl, the first configured URI is used as the default.

Response:

{
	"url": "https://link.ofauth.com/cs_abc123def456",
	"expiresAt": "2024-01-15T10:30:00Z",
	"mode": "hosted"
}

Redirect Query Parameters

After authentication completes, OFAuth redirects users to your URL with query parameters.

All Parameters

Parameter	Type	Present	Description
`status`	string	Always	`success`, `cancelled`, or `error`
`connection_id`	string	On success	The connection ID to use with Access API
`client_reference_id`	string	If provided	Your internal user identifier from `/init`
`step`	string	On cancel	Where the user exited the flow
`error_code`	string	On error	Machine-readable error identifier

Status Values

Value	Meaning
`success`	Authentication completed, `connection_id` is available
`cancelled`	User exited the flow, check `step` for where
`error`	Something went wrong, check `error_code`

Step Values (when `status=cancelled`)

Value	Description
`pre-login`	Before entering credentials
`login`	During credential entry
`2fa`	During two-factor authentication
`authorization`	Reviewing permissions

Error Codes (when `status=error`)

Code	Description
`session_expired`	Link session expired (1 hour limit)
`invalid_credentials`	User entered wrong credentials
`account_locked`	OnlyFans account is locked
`2fa_failed`	Two-factor authentication failed

Retrieve Session Status

Check the current status of a hosted session.

Show GET /v2/link/{clientSecret}

GET /v2/link/{clientSecret}

Parameters:

clientSecret: The client secret from the init response

Response (Different Status States):

// Initial state
{
	"status": "initialized"
}

// User is authenticating
{
	"status": "pending"
}

// Authentication completed
{
	"status": "completed",
	"data": {
		"id": "conn_xyz789",
		"userData": {
			"id": "12345",
			"name": "Jane Doe",
			"username": "janedoe",
			"avatar": "https://example.com/avatar.jpg"
		}
	}
}

Delete Session

Clean up a hosted session.

Show DELETE /v2/link/{clientSecret}

DELETE /v2/link/{clientSecret}

Headers:

apikey: Your API key (required)

Response:

{
	"success": true
}

Security: Allowed Redirect URIs

Your redirectUrl must be pre-registered in your OFAuth dashboard as an Allowed Redirect URI.

Exact Match

We require exact URL matches (scheme, host, path). Query parameters are added by OFAuth on redirect.

HTTPS Required

Always use HTTPS in production. Configure multiple URLs for different environments.

Configure Allowed Redirect URIs per platform in the OFAuth dashboard under Developers → API.

Misconfiguration Behavior

If you pass a redirectUrl not on your allowlist, /v2/link/init returns 400 with Link is misconfigured.
If no Allowed Redirect URIs are configured, you must add at least one before using Link.

Implementation Guide

Step 1: Initialize the Session

const initResponse = await fetch("https://api.ofauth.com/v2/link/init", {
	method: "POST",
	headers: {
		apikey: "YOUR_API_KEY",
		"Content-Type": "application/json"
	},
	body: JSON.stringify({
		redirectUrl: "https://yourapp.com/callback",
		clientReferenceId: "user_123"
	})
})

const { url } = await initResponse.json()

Step 2: Redirect User to Authentication

After initialization, redirect the user to the authentication URL:

window.location.href = url // Redirect to authentication page

Step 3: Handle the Callback

When users complete or cancel authentication, they’ll be redirected to your URL with query params:

// User visits: https://yourapp.com/callback?status=success&connection_id=conn_abc123&client_reference_id=user_123

const params = new URLSearchParams(window.location.search)
const status = params.get("status")
const connectionId = params.get("connection_id")
const clientReferenceId = params.get("client_reference_id")

if (status === "success" && connectionId) {
	// Store connection ID for future API calls
	localStorage.setItem("connectionId", connectionId)
	// Redirect to dashboard or next step
	window.location.href = "/dashboard"
} else if (status === "cancelled") {
	const step = params.get("step")
	console.log(`User cancelled at: ${step}`)
	// Show appropriate message
} else if (status === "error") {
	const errorCode = params.get("error_code")
	console.error(`Authentication failed: ${errorCode}`)
	// Handle error
}

Integration Examples

React Component

import { useState } from "react"

function ConnectOnlyFansButton({ userId }) {
	const [isLoading, setIsLoading] = useState(false)

	const handleConnect = async () => {
		setIsLoading(true)

		try {
			const response = await fetch("/api/auth/init", {
				method: "POST",
				headers: { "Content-Type": "application/json" },
				body: JSON.stringify({ userId })
			})

			const { url } = await response.json()
			window.location.href = url
		} catch (error) {
			console.error("Failed to initialize authentication:", error)
			setIsLoading(false)
		}
	}

	return (
		<button
			onClick={handleConnect}
			disabled={isLoading}
			className="bg-blue-600 text-white px-4 py-2 rounded hover:bg-blue-700">
			{isLoading ? "Connecting..." : "Connect OnlyFans Account"}
		</button>
	)
}

Security Best Practices

Server-Side Verification

Always verify session status server-side, never trust client-side data

HTTPS Only

Use HTTPS for all redirect URLs and API communications

Session Expiry

Link sessions expire after 1 hour for security

State Management

Store connection IDs securely in your database

Error Handling

Session Expired

{
  "error": "Session expired",
  "code": "SESSION_EXPIRED"
}

Solution: Create a new session with /init

Invalid Redirect URL

{
  "error": "Link is misconfigured: invalid redirect URL"
}

Solution: Add the URL to your Allowed Redirect URIs in the dashboard

Authentication Failed

User is redirected with ?status=error&error_code=invalid_credentialsSolution: User needs to retry authentication with correct credentials

Testing

Sandbox Mode: Use sandbox API keys for development. Test sessions work with demo credentials that are provided on the hosted authentication page.

Next Steps

Access API

Use connection IDs to access OnlyFans data

Webhooks

Get notified of connection events

Looking for a fully custom experience? Enterprise Whitelabel mode is available for approved partners who need direct control over authentication flows.

Overview

Quickstart

Use Cases

Guides

Reference

Advanced

​Overview

​How It Works

​Integration Options

Redirect Integration

Popup/Embed Integration

​Base URL

​Authentication

​Core Endpoints

​Initialize Hosted Session

​Redirect Query Parameters

​All Parameters

​Status Values

​Step Values (when status=cancelled)

​Error Codes (when status=error)

​Retrieve Session Status

​Delete Session

​Security: Allowed Redirect URIs

Exact Match

HTTPS Required

​Misconfiguration Behavior

​Implementation Guide

​Step 1: Initialize the Session

​Step 2: Redirect User to Authentication

​Step 3: Handle the Callback

​Integration Examples

​React Component

​Security Best Practices

Server-Side Verification

HTTPS Only

Session Expiry

State Management

​Error Handling

​Testing

​Next Steps

Access API

Webhooks

Overview

How It Works

Integration Options

Base URL

Authentication

Core Endpoints

Initialize Hosted Session

Redirect Query Parameters

All Parameters

Status Values

Step Values (when `status=cancelled`)

Error Codes (when `status=error`)

Retrieve Session Status

Delete Session

Security: Allowed Redirect URIs

Misconfiguration Behavior

Implementation Guide

Step 1: Initialize the Session

Step 2: Redirect User to Authentication

Step 3: Handle the Callback

Integration Examples

React Component

Security Best Practices

Error Handling

Testing

Next Steps