Connections

Connections represent authenticated OnlyFans accounts linked to your organization. There are two ways to create connections:

Link authentication — Users authenticate through OFAuth’s secure Link flow. OFAuth handles credentials, 2FA, and session management.
Import — You provide existing OnlyFans session data directly via the API. Useful if you manage authentication yourself or are migrating from another system.

Both types produce a Connection ID that you use with the Access API to interact with OnlyFans data.

Creating Connections via Link

Obtaining Connection IDs

After a user completes authentication through Link, you receive the connection ID through one of these methods:

Method	When to Use
`connection.created` webhook	Recommended. Server-side, reliable, includes full details
Embed `onSuccess` callback	Client-side, immediate feedback for embedded flows
Redirect query params	Hosted redirect flow, `connection_id` in URL

Using Client Reference ID

The clientReferenceId you provide when initializing a Link session is your key to mapping connections to users in your system:

// 1. When initializing Link, pass your internal user ID
const session = 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_abc123" // Your internal user ID
  })
});

const sessionData = await session.json();
if (sessionData.mode !== "hosted") {
  throw new Error(`Expected hosted Link session, received ${sessionData.mode}`);
}

// 2. In webhook handler, use clientReferenceId to store the connection
app.post("/webhooks/ofauth", async (req, res) => {
  const { type, data } = req.body;
  
  if (type === "connection.created") {
    // Use clientReferenceId to find your user and store their connection
    await db.users.update({
      where: { id: data.clientReferenceId },
      data: { connectionId: data.connection.id }
    });
  }
  
  res.status(200).send("ok");
});

Always pass a clientReferenceId when initializing Link sessions. This is the recommended way to correlate connections back to your users, especially when using webhooks.

Importing Connections

If you manage OnlyFans authentication yourself, you can import sessions directly. Imported connections are not billed monthly and are not health-checked by the connection monitor. They can be used through the Access API immediately.

Import a Connection

POST /v2/account/connections/import

Field	Type	Required	Description
`cookie`	string	Yes	OnlyFans session cookie. Must contain `auth_id`, `sess`, and `fp` values.
`userAgent`	string	Yes	The user agent string used to create the session.
`permissions`	string[]	No	Permissions to grant. Defaults to organization permissions.
`clientReferenceId`	string	No	Your internal reference ID for tracking.

OFAuth validates the session by making a request to OnlyFans and automatically fetches the user’s profile data. If the session is invalid or expired, the import will fail.

curl -X POST https://api.ofauth.com/v2/account/connections/import \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cookie": "auth_id=123456; sess=your_session_token; fp=your_fingerprint",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 ...",
    "clientReferenceId": "user_abc123"
  }'

const response = await fetch("https://api.ofauth.com/v2/account/connections/import", {
  method: "POST",
  headers: {
    apikey: "YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    cookie: "auth_id=123456; sess=your_session_token; fp=your_fingerprint",
    userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 ...",
    clientReferenceId: "user_abc123"
  })
})

const connection = await response.json()
console.log("Imported:", connection.id, connection.userData.username)

import requests

response = requests.post(
    "https://api.ofauth.com/v2/account/connections/import",
    headers={
        "apikey": "YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "cookie": "auth_id=123456; sess=your_session_token; fp=your_fingerprint",
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 ...",
        "clientReferenceId": "user_abc123"
    }
)

connection = response.json()
print("Imported:", connection["id"], connection["userData"]["username"])

The response includes the full connection object with imported: true and the user’s profile data fetched from OnlyFans.

If an active connection with the same OnlyFans user already exists, the import returns a 409 error with the existing connection ID. You can update the session on the existing connection using the update endpoint instead.

Updating an Imported Session

If an imported connection’s session expires or needs to be rotated, you can update it in place without deleting and re-importing. This preserves the connection ID.

PATCH /v2/account/connections/import/{connectionId}

Field	Type	Required	Description
`cookie`	string	Yes	New OnlyFans session cookie. Must contain `auth_id`, `sess`, and `fp` values.
`userAgent`	string	Yes	The user agent string used to create the new session.

The new session is validated against OnlyFans and must belong to the same OnlyFans user as the existing connection. If the user ID from the new cookie doesn’t match, the request returns a 409 error.

curl -X PATCH https://api.ofauth.com/v2/account/connections/import/conn_abc123xyz \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cookie": "auth_id=123456; sess=new_session_token; fp=new_fingerprint",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 ..."
  }'

const response = await fetch("https://api.ofauth.com/v2/account/connections/import/conn_abc123xyz", {
  method: "PATCH",
  headers: {
    apikey: "YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    cookie: "auth_id=123456; sess=new_session_token; fp=new_fingerprint",
    userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 ..."
  })
})

const connection = await response.json()
console.log("Updated:", connection.id, connection.status)

import requests

response = requests.patch(
    "https://api.ofauth.com/v2/account/connections/import/conn_abc123xyz",
    headers={
        "apikey": "YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "cookie": "auth_id=123456; sess=new_session_token; fp=new_fingerprint",
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 ..."
    }
)

connection = response.json()
print("Updated:", connection["id"], connection["status"])

On success, the connection status is set back to active and the response includes updated user profile data from OnlyFans.

This endpoint only works for imported connections (imported: true). Link-managed connections cannot be updated through this endpoint.

Filtering by Type

List only imported or Link-created connections:

GET /v2/account/connections?imported=true
GET /v2/account/connections?imported=false

Connection States

State	Description
`active`	Ready for API access
`awaiting_2fa`	Waiting for 2FA verification
`expired`	Session ended, re-authentication needed

Connection Lifecycle

Connections may expire due to:

OnlyFans session expiration
User password changes
Extended inactivity

Set up System Webhook Events to receive connection.expired events.

API Reference

List Connections

GET /v2/account/connections

Parameter	Type	Description
`limit`	integer	Max results (default: 10)
`offset`	integer	Skip count (default: 0)
`status`	string	Filter: `active`, `expired`, `awaiting_2fa`
`imported`	string	Filter: `true` (imported only), `false` (Link-created only)

Response shape:

{
  "list": [
    {
      "id": "conn_abc123xyz",
      "status": "active",
      "permissions": ["profile:read"],
      "expiredAt": null,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z",
      "clientReferenceId": "user_abc123",
      "imported": false,
      "lastCheckedAt": "2024-01-15T10:35:00.000Z",
      "userData": {
        "id": "123456",
        "name": "Jane Doe",
        "username": "janedoe",
        "avatar": "https://..."
      }
    }
  ],
  "hasMore": false
}

Delete Connection

DELETE /v2/account/connections/{connectionId}

Deleting a connection logs the user out, stops billing, permanently removes the connection record, and sends a connection.disconnected webhook.

Invalidate Connection

POST /v2/account/connections/{connectionId}/invalidate

Invalidates a connection by marking it as expired and logging out the user. Unlike deletion, the connection record is preserved, making it ideal for:

Updating permissions: When your platform’s required permissions change, invalidate the connection so users reconnect with the new permission set
Security rotation: Force users to re-authenticate without losing their connection history
Graceful session refresh: Refresh credentials while maintaining connection metadata

When you invalidate a connection, the user’s profile data and permissions configuration are preserved. Only the session data is cleared.

Updating User Data Permissions

When your platform needs to request different permissions from connected accounts, use the invalidate + reconnect flow:

Step 1: Update Your Platform Permissions

In your OFAuth Dashboard, update the User Data Permissions to include the new permissions your platform requires.

Step 2: Invalidate Existing Connections

curl -X POST https://api.ofauth.com/v2/account/connections/{connectionId}/invalidate \
  -H "apikey: YOUR_API_KEY"

This marks the connection as expired without deleting it.

Step 3: Prompt User to Reconnect

When users reconnect through Link with the same connectionId, they’ll be prompted to approve the updated permissions:

curl -X POST https://api.ofauth.com/v2/link/init \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connectionId": "conn_abc123xyz",
    "redirectUrl": "https://yourapp.com/callback"
  }'

Set up webhooks to listen for connection.expired events, then notify affected users to reconnect with the updated permissions.

Invalidate vs Delete

Action	Session	Record	User Data	Use Case
Invalidate	Cleared	Preserved	Preserved	Permission updates, security rotation
Delete	Cleared	Removed	Removed	User requests disconnection, stop billing

Invalidated connections send connection.expired and can be reconnected with the same connection ID. Deleted connections send connection.disconnected and cannot be reconnected or renewed.

Reconnecting Expired Connections

When a connection expires, you can reconnect the same OnlyFans account without creating a duplicate connection. Pass the existing connectionId when initializing a new Link session:

curl -X POST https://api.ofauth.com/v2/link/init \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connectionId": "conn_abc123xyz",
    "redirectUrl": "https://yourapp.com/callback"
  }'

Parameter	Type	Description
`connectionId`	string	Existing connection ID to reconnect. Must start with `conn_`.

When a valid connectionId is provided:

The user completes authentication through Link
The existing connection is updated with fresh session data
Connection ID remains the same, preserving your references

When an invalid or non-existent connectionId is provided:

The system automatically creates a new connection instead
No error is thrown—this allows graceful handling of deleted connections

Use reconnection for expired connections to maintain consistent connection IDs in your database and avoid duplicate records.

Best Practices

Monitor status via webhooks
Handle expiration with re-auth flows using connectionId
Store securely - treat connection IDs as credentials
Clean up unused connections to stop billing

Next Steps

Access API

Use connections to access data

System Webhook Events

Monitor connection events

Authentication

Realtime

Messaging

Content

Media

Management

Creating Connections via Link

Obtaining Connection IDs

Using Client Reference ID

Importing Connections

Import a Connection

Updating an Imported Session

Filtering by Type

Connection States

Connection Lifecycle

API Reference

List Connections

Delete Connection

Invalidate Connection

Updating User Data Permissions

Step 1: Update Your Platform Permissions

Step 2: Invalidate Existing Connections

Step 3: Prompt User to Reconnect

Invalidate vs Delete

Reconnecting Expired Connections

Best Practices

Next Steps

Access API

System Webhook Events

​Creating Connections via Link

​Obtaining Connection IDs

​Using Client Reference ID

​Importing Connections

​Import a Connection

​Updating an Imported Session

​Filtering by Type

​Connection States

​Connection Lifecycle

​API Reference

​List Connections

​Delete Connection

​Invalidate Connection

​Updating User Data Permissions

​Step 1: Update Your Platform Permissions

​Step 2: Invalidate Existing Connections

​Step 3: Prompt User to Reconnect

​Invalidate vs Delete

​Reconnecting Expired Connections

​Best Practices

​Next Steps

Access API

System Webhook Events

Creating Connections via Link

Obtaining Connection IDs

Using Client Reference ID

Importing Connections

Import a Connection

Updating an Imported Session

Filtering by Type

Connection States

Connection Lifecycle

API Reference

List Connections

Delete Connection

Invalidate Connection

Updating User Data Permissions

Step 1: Update Your Platform Permissions

Step 2: Invalidate Existing Connections

Step 3: Prompt User to Reconnect

Invalidate vs Delete

Reconnecting Expired Connections

Best Practices

Next Steps