Initialize Link Session

Create a new hosted or embedded 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'));
}