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
redirectUrlstringNoURL to redirect to after completion. If omitted, uses the first Allowed Redirect URI from your dashboard.
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.
The redirectUrl must be pre-registered in your OFAuth dashboard under Developers → API → Allowed Redirect URIs.

​
Response

{
  "url": "https://link.ofauth.com/cs_abcdef123456...",
  "expiresAt": "2023-10-27T10:00:00.000Z",
  "mode": "hosted"
}
FieldTypeDescription
urlstringThe URL to redirect the user to.
expiresAtstringISO timestamp when this session expires (usually 30-60 minutes).
modestringThe mode the session was initialized in.

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