Initialize Link Session

Overview

The /init endpoint creates a new Link session. It returns a discriminated response:

mode: "hosted" with a url you can redirect to or open in the Link embed popup
mode: "whitelabel" with a clientSecret for enterprise programmatic flows

HTTP Request

POST https://api.ofauth.com/v2/link/init
apikey: YOUR_API_KEY
Content-Type: application/json

Request Body

Field	Type	Required	Description
`clientAppId`	`string`	Recommended	Your client app ID (e.g., `app_abc123`). If omitted, the first matching client app for your environment is used automatically.
`redirectUrl`	`string`	No	URL to redirect to after completion. Must be registered in your client app’s Allowed Redirect URIs. If omitted, uses the first allowed URI from your client app.
`clientReferenceId`	`string`	No	Your own internal ID for this user. Returned in webhooks and query params.
`connectionId`	`string`	No	Provide an existing connection ID to reconnect/re-authenticate that specific connection.
`geolocation`	`object`	No	Override the proxy location for this session.
`geolocation.country`	`string`	Yes*	Country code (e.g., `"US"`). *Required if `geolocation` is provided.
`geolocation.state`	`string`	No	State/region code (e.g., `"CA"` for California).

The redirectUrl must be registered in your client app’s Allowed Redirect URIs. Create and configure client apps in your OFAuth dashboard.

Response

{
  "mode": "hosted",
  "url": "https://link.ofauth.com/cs_abcdef123456...",
  "expiresAt": "2023-10-27T10:00:00.000Z"
}

Field	Type	Description
`mode`	`"hosted" \| "whitelabel"`	The Link session type returned for this request.
`url`	`string`	Present when `mode` is `hosted`. Redirect the user to this URL or open it in the Link embed popup.
`clientSecret`	`string`	Present when `mode` is `whitelabel`. Use it with the whitelabel session endpoints.
`expiresAt`	`string`	ISO timestamp when this session expires (usually 30-60 minutes).

Redirect Query Parameters

After Link completes, OFAuth redirects the user to your redirectUrl with query parameters appended:

On Success

https://yourapp.com/callback?status=success&connection_id=conn_abc123&client_reference_id=user_456

Param	Description
`status`	`success`
`connection_id`	The new or updated connection ID
`client_reference_id`	Your reference ID (if provided in init)

On Cancel

https://yourapp.com/callback?status=cancelled&step=authorization&client_reference_id=user_456

Param	Description
`status`	`cancelled`
`step`	Where the user cancelled: `pre-login`, `authorization`, `login`, or `2fa`
`client_reference_id`	Your reference ID (if provided)

On Error

https://yourapp.com/callback?status=error&error_code=session_expired&client_reference_id=user_456

Param	Description
`status`	`error`
`error_code`	Error type: `session_expired`, `invalid_credentials`, etc.
`client_reference_id`	Your reference ID (if provided)

Example

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://myapp.com/callback",
    "clientReferenceId": "user_123"
  }'

If you are using a hosted Link flow, verify that mode === "hosted" before reading url.

Handling the Callback

// On your callback page
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') {
  // Store connectionId, fetch user data via API
  console.log('Connected!', connectionId);
} else if (status === 'cancelled') {
  console.log('User cancelled at step:', params.get('step'));
} else if (status === 'error') {
  console.log('Error:', params.get('error_code'));
}

Account API

Link API

Access API

Vault+ API

Realtime OnlyFans Events

System Webhook Events

Dynamic Rules API

Initialize Link Session

Overview

HTTP Request

Request Body

Response

Redirect Query Parameters

On Success

On Cancel

On Error

Example

Handling the Callback

​Overview

​HTTP Request

​Request Body

​Response

​Redirect Query Parameters

​On Success

​On Cancel

​On Error

​Example

​Handling the Callback

Overview

HTTP Request

Request Body

Response

Redirect Query Parameters

On Success

On Cancel

On Error

Example

Handling the Callback