Skip to main content

​
Overview

The /init endpoint creates a new Link session. It returns a URL that you can redirect the user to (Hosted mode) or load in an iframe/popup (Embed mode).

​
HTTP Request

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

​
Request Body

FieldTypeRequiredDescription
clientAppIdstringRecommendedYour client app ID (e.g., app_abc123). If omitted, the first matching client app for your environment is used automatically.
redirectUrlstringNoURL 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.
clientReferenceIdstringNoYour own internal ID for this user. Returned in webhooks and query params.
connectionIdstringNoProvide an existing connection ID to reconnect/re-authenticate that specific connection.
geolocationobjectNoOverride the proxy location for this session.
geolocation.countrystringYes*Country code (e.g., "US"). *Required if geolocation is provided.
geolocation.statestringNoState/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

{
  "url": "https://link.ofauth.com/cs_abcdef123456...",
  "expiresAt": "2023-10-27T10:00:00.000Z"
}
FieldTypeDescription
urlstringThe URL to redirect the user to.
expiresAtstringISO 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
ParamDescription
statussuccess
connection_idThe new or updated connection ID
client_reference_idYour reference ID (if provided in init)

​
On Cancel

https://yourapp.com/callback?status=cancelled&step=authorization&client_reference_id=user_456
ParamDescription
statuscancelled
stepWhere the user cancelled: pre-login, authorization, login, or 2fa
client_reference_idYour reference ID (if provided)

​
On Error

https://yourapp.com/callback?status=error&error_code=session_expired&client_reference_id=user_456
ParamDescription
statuserror
error_codeError type: session_expired, invalid_credentials, etc.
client_reference_idYour 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"
  }'

​
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'));
}