Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ofauth.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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

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

{
  "mode": "hosted",
  "url": "https://link.ofauth.com/cs_abcdef123456...",
  "expiresAt": "2023-10-27T10:00:00.000Z"
}
FieldTypeDescription
mode"hosted" | "whitelabel"The Link session type returned for this request.
urlstringPresent when mode is hosted. Redirect the user to this URL or open it in the Link embed popup.
clientSecretstringPresent when mode is whitelabel. Use it with the whitelabel session endpoints.
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"
  }'
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'));
}