> ## 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 deep linking 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 a deep link or universal link so the OAuth callback returns the user to your app.

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

### Deep linking

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

```
myapp://callback?loginId={loginId}&institution={institution}
```

Configure your app to handle this deep link 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 deep link |
| Android Chrome  | OAuth redirect returns to your app via deep link |
| WebView         | OAuth flow completes without blocked pop-ups     |

Use the [Toolbox sandbox](/guides/getting-started/testing-environments) with Flinks Capital for initial testing. Note that Flinks Capital does not use OAuth — you'll need to test OAuth flows with real US institutions in your production environment.