> ## 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.

# 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

```http theme={null}
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).                                                                                                                 |

<Info>
  The `redirectUrl` must be registered in your client app's Allowed Redirect URIs. Create and configure client apps in your [OFAuth dashboard](https://app.ofauth.com/platform/apps).
</Info>

## Response

```json theme={null}
{
  "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

```bash theme={null}
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

```javascript theme={null}
// 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'));
}
```