OnlyFans API Complete Developer Guide 2025

Building on OnlyFans sucks.

Not because the platform is bad—it's not. It's because OnlyFans changes how their API works every few weeks. Your auth breaks. Your signing logic throws 401s. That "refresh the page" error becomes your nemesis.

This 2025 guide serves as comprehensive OnlyFans API documentation for teams looking to build stable integrations. Unlike brittle DIY scraping approaches, OFAuth provides the infrastructure to ship features, not debug HTTP headers.

Quick Start: Integrate OFAuth in 3 Steps

Connect: Initialize Link session → redirect to hosted auth → receive connection ID (Link docs)

Access: Call Access API with apikey + x-connection-id for stable, signed requests (Access API docs)

Monitor: Add retries with backoff, idempotency keys, circuit breakers, and observability (Rate limiting)

Most teams ship production features in 1-2 weeks using this pattern.

What You' learn

How to connect OnlyFans accounts without storing credentials
Two ways to call the OnlyFans API (managed vs. direct)
Production patterns for reliability, retries, and rate limits
Real-world examples for dashboards, messaging, content, and analytics

Assumption: You're building a tool for creators, agencies, or fans. You need stable API access without the operational nightmare.

The OnlyFans API Problem

OnlyFans doesn't publish an official developer API. Everything is reverse-engineered from their web app. This means:

Request signing changes constantly. What works today breaks next week.
Sessions expire unpredictably. No refresh token flow. Just sudden 401s.
Rate limits are opaque. You find out by getting throttled.
No documentation. You're on your own.

If you build directly on top of this, you're signing up for maintenance hell. Every signing change becomes an emergency. Every session rotation bug becomes a 3am page.

OFAuth exists to absorb this chaos so you don't have to. It accelerates OnlyFans integration across dashboards, messaging, and automation platforms.

Two Ways to Integrate

You have two paths for your OnlyFans integration:

1. Access API (Recommended)

OFAuth handles everything: auth, signing, session management, retries. You call clean REST endpoints. When OnlyFans changes something, OFAuth updates it and your app keeps working.

Use this if: You want to ship features, not debug HTTP headers.

2. Direct Calls + Dynamic Rules (Advanced)

You call OnlyFans directly. OFAuth gives you current signing parameters via Dynamic Rules. When OnlyFans changes them, you update your code.

Use this if: You already have a custom proxy or need experimental endpoints that Access doesn't cover yet.

Access API vs Direct Calls: Decision Guide

Choose Access API when:

Building dashboards, analytics, CRM, or standard product features

Optimizing for speed-to-market and maintainability

You want automatic session management and signing

Choose Direct Calls when:

Operating a custom proxy with specialized needs

Willing to manage upstream changes and failure modes

Need ultimate control over request timing and surfaces

Start with Access API. Add direct calls only when necessary.

Most teams start with Access and only use Dynamic Rules when absolutely necessary. Start simple.

Step 1: Connect Accounts with Link

Before you can call the API, you need users to connect their OnlyFans accounts.

Bad way: Ask for username/password. Store credentials. Pray you don't get breached.

Good way: Use OFAuth Link. You get a connectionId. No raw credentials touch your database. Follow OAuth 2.0 best practices for secure credential handling.

How Link Works

User clicks "Connect OnlyFans Account" in your app
You redirect them to OFAuth's hosted auth flow
User logs in to OnlyFans (on OFAuth's domain, not yours)
OFAuth redirects back with a connection ID
You store the connection ID and use it for all API calls

Code Example

Initialize a Link session:

curl -X POST https://api.ofauth.com/v2/link/init 
  -H "apikey: YOUR_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "clientAppId": "app_your_client_app_id",
    "redirectUrl": "https://yourapp.com/connect/callback",
    "clientReferenceId": "user_123"
  }'

Response:

{
	"url": "https://link.ofauth.com/abc123",
	"clientSecret": "cs_xyz789"
}

Redirect user to the url. After they connect, OFAuth sends them to your redirectUrl with the connection ID in the query string.

Done. No credentials stored.

Step 2: Call the Access API

Now that you have a connection ID, you can call the OnlyFans API through OFAuth's Access API.

Two types of endpoints:

Managed endpoints - Stable, typed routes for common data (user profile, posts, messages, stats)
Proxy endpoints - Passthrough to any OnlyFans endpoint (for long-tail or experimental calls)

Example: Get User Profile

curl -H "apikey: YOUR_API_KEY" 
     -H "x-connection-id: conn_abc123" 
     https://api.ofauth.com/v2/access/self/me

Response:

{
  "id": "123456",
  "username": "creator",
  "name": "Creator Name",
  ...
}

Example: Proxy Request

For endpoints not covered by managed routes:

curl -H "apikey: YOUR_API_KEY" 
     -H "x-connection-id: conn_abc123" 
     https://api.ofauth.com/v2/access/proxy/users/me/posts

This hits OnlyFans' /users/me/posts endpoint, but OFAuth handles signing and session management for you.

Step 3: Handle Sessions and Errors

OnlyFans sessions expire. Sometimes immediately. You need to handle this gracefully.

Error Taxonomy

400: "Please refresh the page" - signing parameters changed
401: Session expired or invalid connection ID
403: Blocked or rate-limited
429: Definitely rate-limited
5xx: OnlyFans is having a bad day

Retry Strategy

Implement exponential backoff with jitter to avoid thundering herds.

async function callAPI(endpoint, retries = 3) {
	for (let i = 0; i < retries; i++) {
		try {
			const response = await fetch(endpoint);
			if (response.ok) return response.json();

			if (response.status === 401) {
				// Session expired - prompt reconnect
				throw new SessionExpiredError();
			}

			if (response.status === 429 || response.status === 403) {
				// Rate limited - backoff
				await sleep(Math.pow(2, i) * 1000 + Math.random() * 1000);
				continue;
			}

			if (response.status >= 500) {
				// OnlyFans issue - retry
				await sleep(Math.pow(2, i) * 1000);
				continue;
			}

			// Other error - don't retry
			throw new APIError(response);
		} catch (error) {
			if (i === retries - 1) throw error;
		}
	}
}

Key points:

Exponential backoff for retries (don't hammer the API)
Jitter to avoid thundering herds
Circuit breakers to fail fast when OnlyFans is down
Surface reconnect UX when sessions expire

Production Patterns

Rate Limiting

OnlyFans has rate limits. We don't know what they are (they don't publish them), but here's what works:

Max 2 requests/second per connection as a safe default
Use queues to smooth request bursts
Track 429s and back off aggressively

Idempotency

Make your writes idempotent. OnlyFans doesn't provide idempotency keys, so use Stripe's idempotency approach as a reference implementation:

Generate request IDs on your side
Check before writing (e.g., "does this message already exist?")
Handle duplicate 200s gracefully

Timeouts

10-20s for reads (user data, posts, stats)
30-60s for writes (messages, uploads, edits)
120s max globally (with circuit breaker)

Caching

Cache aggressively:

Profile data: 5-10 minutes
Stats/earnings: 1-5 minutes
Posts/messages: Don't cache (too dynamic)

Invalidate on writes or when you get stale data signals.

Common Use Cases

Creator Dashboards

Pull earnings, subscriber counts, post performance:

# Earnings summary
GET /v2/access/self/earnings/summary

# Subscriber list
GET /v2/access/self/subscribers

# Post stats
GET /v2/access/self/posts/{postId}/stats

Pre-compute aggregates overnight. Don't recalculate 90-day earnings on every page load. Building a custom OnlyFans CRM for agencies? Start with these core metrics.

Messaging Automation

Send messages, handle DMs:

# Send message
POST /v2/access/proxy/chats/{chatId}/messages

# Get inbox
GET /v2/access/proxy/chats

Respect rate limits. Queue messages. Make sends idempotent. Learn how to go beyond the feed by accessing messages and stories via API.

Content Management

Schedule posts, manage media:

# Upload media
POST /v2/access/proxy/media/upload

# Create post
POST /v2/access/proxy/posts

Important: Don't store OnlyFans media locally. Use OFAuth's Vault+ to serve media via proxied URLs. This keeps you compliant with data retention policies and ensures media stays accessible even if source URLs expire.

Provide audit logs for all creator actions (posts, edits, deletes).

Analytics

Track subscriber trends, content performance, revenue:

# Subscriber history
GET /v2/access/self/subscribers/history

# Revenue breakdown
GET /v2/access/self/earnings/breakdown

Use rolling windows (7/30/90 days). Cache heavily. Update async.

Direct Calls with Dynamic Rules

If you need to call OnlyFans directly (not through Access API), you'll need current signing parameters.

OnlyFans changes these frequently. When they do, your requests fail with 400 "Please refresh the page" or 401.

How Dynamic Rules Works

Fetch current signing parameters from OFAuth
Use them to sign your requests
When you get 400/401, refresh parameters and retry

This gives you maximum control but requires you to handle signing changes yourself.

Most teams don't need this. Use Access API unless you have a specific reason not to.

Security Checklist

Review the OWASP API Security Top 10 for a production security checklist.

Never store OnlyFans credentials
Never store OnlyFans media locally (use Vault+ proxied URLs)
Keep API keys server-side only (never in browser)
Use HTTPS everywhere
Delete stored profile/stats data within 30 days of user disconnect
Log access to sensitive data (earnings, subscriber PII)
Implement role-based access (content vs. finance vs. operations)
Audit credential access regularly

Testing Strategy

Use OFAuth sandbox with demo creators
Seed predictable data for E2E tests
Test the full flow: connect → fetch → write
Simulate OnlyFans failures (503s, 429s, session expiry)
Load test with realistic request patterns

Observability

Adopt OpenTelemetry standards for distributed tracing. Track these metrics:

Request latency by endpoint
Error rate (400, 401, 403, 429, 5xx)
Retry count per request
Queue depth for async jobs
Session expiry events

Alert on:

Error rate spikes (>5% sustained)
Unusual 401 clusters (signing changes)
Rate limit threshold hits (>80% of limit)

Tag traces with connection IDs (not user secrets) for debugging.

Troubleshooting Common Issues

400 "Please refresh the page" Errors

Cause: Stale Dynamic Rules (OnlyFans rotated signing parameters)
Solution: Refresh rules via webhook or conditional logic; implement circuit breaker

401 Unauthorized Errors

Cause: Expired session or invalid connection ID
Solution: Prompt user to reconnect via Link; check session expiry handling

403 Forbidden Errors

Cause: Rate limiting or insufficient permissions
Solution: Implement exponential backoff; verify account permissions

Connection Timeout Errors

Cause: Network latency or upstream slowness
Solution: Increase timeout to 20-60s for uploads; add retry logic

Performance Benchmarks

Typical latency for common operations (p50/p95):

Access API profile fetch: 120ms / 280ms
Access API message send: 180ms / 450ms
Link session init: 80ms / 150ms
Proxy endpoint call: 200ms / 500ms
Dynamic Rules refresh: 50ms / 120ms

For high-throughput workloads (>1000 req/min), batch operations and use cursor-based pagination.

FAQ

What happens when OnlyFans changes signing? With Access API: Nothing. OFAuth updates it. Your app keeps working. With Direct Calls: You get 400/401 errors. Fetch new parameters from Dynamic Rules and update your signing code.

How do I keep users connected? Use Link. Don't store credentials. When sessions expire, show a clean "Reconnect OnlyFans" prompt.

Can I build without OFAuth? Yes, but you'll spend 40% of your time maintaining auth and signing logic instead of building features. Most teams try it, then switch to OFAuth after the third emergency signing fix at 2am.

Does OFAuth support webhooks? Yes. You can subscribe to events like connection status changes, rules updates, and data sync completions.

What's the latency overhead? Typically 50-200ms vs. direct OnlyFans calls. Worth it for the operational simplicity.

How does OFAuth handle OnlyFans API rate limits? Access API automatically respects upstream rate limits and returns 429 status codes with Retry-After headers. Implement exponential backoff and jitter to avoid hitting limits.

Can I use OFAuth in a multi-tenant SaaS application? Yes. Store one connection ID per user/organization. Use your own auth layer to scope API calls to the appropriate connection. OFAuth supports unlimited connections per API key.

Rollout Checklist

Week 1: Integrate Link, connect test accounts
Week 2: Build one read-only feature (dashboard or stats)
Week 3: Add writes (messages or posts)
Week 4: Production testing with real creators
Week 5+: Scale and iterate

Start with managed Access endpoints. Only add proxy or Direct Calls when you hit real limitations.

Get the Integration Starter Kit

Download our OFAuth Integration Checklist and Postman Collection to ship your first feature in 1-2 days.

Download Free Starter Kit →

Summary

The OnlyFans API is a moving target. You can either:

Spend endless hours maintaining auth, signing, and session rotation
Use OFAuth and ship features instead

Most teams pick option 2. You get:

Secure account connections (no credentials stored)
Stable API access (managed endpoints + proxy)
Automatic handling of OnlyFans changes
Production patterns that actually work

Start with Link + Access API. Ship features. Scale from there.

If you're building dashboards, messaging, content tools, or analytics—this is the fast path.

Questions? Check the full OFAuth docs or book a technical walkthrough.