> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flinks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth Integration

> Set up Flinks Connect with OAuth for web and mobile platforms, including universal links and WebView configuration.

Many US financial institutions use OAuth for authentication. When a customer selects an OAuth-supported institution in Flinks Connect, they are redirected to their bank's website to authorize the connection, then redirected back.

## Web integration

### iframe setup

Embed Flinks Connect as an iframe with the required `redirectUrl` parameter:

```html theme={null}
<iframe
  height="760"
  src="https://{instance}-iframe.private.fin.ag/?redirectUrl=https://example.com/callback&consentEnable=true"
></iframe>
```

### Handling events

Use the Event Listener to track the OAuth flow:

```html theme={null}
<script>
  window.addEventListener("message", function (e) {
    const data = e.data;
    switch (data.step) {
      case "APP_MOUNTED":
        // Flinks Connect loaded successfully
        break;
      case "INSTITUTION_SELECTED":
        // User selected their financial institution
        break;
      case "REDIRECT":
        // User completed the flow, capture the loginId
        console.log("loginId:", data.loginId);
        break;
      case "POPUP_BLOCKED":
        // OAuth pop-up was blocked by the browser
        break;
      case "POPUP_OPENED":
        // OAuth authorization window opened
        break;
    }
  });
</script>
```

<Warning>
  Ensure your website allows pop-ups from the Flinks domain, as OAuth connections open the bank's authorization page in a new window.
</Warning>

## Mobile integration

For mobile apps, OAuth requires special handling because WebViews may not fully support the redirect flow.

### Recommended approach: system browser

Use the device's system browser (Safari on iOS, Chrome on Android) instead of a WebView for the best OAuth experience:

1. Open Flinks Connect in the system browser using your iframe URL.
2. Add `oauthWindowRedirect=true` to enable full-page redirects instead of pop-ups.
3. Set up an HTTPS universal link (iOS) or App Link (Android) so the OAuth callback returns the user to your app.

<Warning>
  Flinks only supports `https` redirect URIs. Custom URI schemes such as `myapp://` are not supported. Use an HTTPS URL that your app claims through universal links or App Links.
</Warning>

```
https://{instance}-iframe.private.fin.ag/?oauthWindowRedirect=true&redirectUrl=https://yourapp.com/callback&...
```

### Returning to your app

After the OAuth flow completes, Flinks redirects to your `redirectUrl` with the `loginId`:

```
https://yourapp.com/callback?loginId={loginId}&institution={institution}
```

Configure your app's universal link (iOS) or App Link (Android) to open on this HTTPS URL and extract the `loginId`.

### WebView configuration

If you must use a WebView, configure it properly:

<Tabs>
  <Tab title="iOS">
    * Use `SFSafariViewController` or `ASWebAuthenticationSession` for the OAuth flow
    * Standard `WKWebView` may block redirects to external domains
    * Ensure your app's domain is properly configured for universal links
  </Tab>

  <Tab title="Android">
    * Enable JavaScript in your WebView: `webView.getSettings().setJavaScriptEnabled(true)`
    * Enable DOM storage: `webView.getSettings().setDomStorageEnabled(true)`
    * Handle external URLs by opening them in the system browser
  </Tab>

  <Tab title="Hybrid (React Native, Flutter)">
    * Set `webview=true` in the iframe URL parameters
    * Use `oauthWindowRedirect=true` for OAuth institutions
    * Handle the redirect URL in your native code to capture the `loginId`
  </Tab>
</Tabs>

## Testing

Test your OAuth integration across multiple environments:

| Platform        | What to verify                                        |
| :-------------- | :---------------------------------------------------- |
| Desktop browser | Pop-up opens and redirects work correctly             |
| iOS Safari      | OAuth redirect returns to your app via universal link |
| Android Chrome  | OAuth redirect returns to your app via App Link       |
| WebView         | OAuth flow completes without blocked pop-ups          |

### Simulate an OAuth flow in the Toolbox

You can test the full front-end OAuth experience in the [Toolbox](/guides/getting-started/testing-environments) by adding `demoOutbound=true` to the iframe URL. This routes the Flinks Capital demo institution through the OAuth flow, so you can walk the OAuth screens end to end with sandbox data.

<Steps>
  <Step title="Generate an Authorize Token">
    Call `/GenerateAuthorizeToken` with your `customerId`, instance, and `flinks-auth-key` to obtain a token for the iframe. Use the [Toolbox credentials](/guides/getting-started/testing-environments#toolbox-credentials).
  </Step>

  <Step title="Load the iframe in OAuth demo mode">
    Load Flinks Connect with `demoOutbound=true` and the token you generated:

    ```
    https://{instance}-iframe.private.fin.ag/v2/?demoOutbound=true&authorizeToken={token}
    ```
  </Step>

  <Step title="Walk through the simulated OAuth screens">
    The demo reproduces the full front-end OAuth sequence:

    1. Consent page
    2. Financial institution selection
    3. FI redirecting page
    4. FI online banking: username / password
    5. FI online banking: consent screen
    6. FI online banking: account selection
    7. Success page (returns the `loginId`)
  </Step>
</Steps>

<Note>
  `demoOutbound=true` runs the Flinks Capital demo institution through the OAuth flow, which is how you exercise the OAuth screens in the sandbox. When you're ready for end-to-end validation against a real OAuth institution, use a client (production) instance.
</Note>