# OAuth Support Guide

## Overview

Some financial institutions require an OAuth authorization flow to connect user accounts. This guide explains how to properly configure the Pluggy Connect widget to handle OAuth redirections across different platforms and devices.

By following these guidelines, you can ensure a smooth OAuth integration experience for your users across various platforms and devices.

### What OAuth changes for your integration

OAuth is an access-delegation standard: instead of typing credentials into your
application, the user authorizes it inside the institution's own interface and the
institution issues a token. Two things follow from that, and both are why these
connectors need extra setup on your side:

- **The user leaves your application** — they authenticate at the institution and
  have to be brought back. That return trip is what `oauthRedirectUri` is for.
- **The connection refreshes without asking again.** An OAuth token can be renewed,
  so the connection stays alive without sending the user through the login every
  time — which is also why these connections tend to break less than credential-based
  ones.

The one thing that reliably goes wrong is the return trip. Some mobile browsers will
not let the authorization window close itself, and without a redirect URI the user is
left staring at a finished authorization page with no way back to your app.

## Setting Up the OAuth Redirect URI

To handle redirections after the OAuth process, you need to define an `oauthRedirectUri`. This URI is used to redirect users back to your application after they have completed the OAuth process with the financial institution.

### Requirements

The `oauthRedirectUri` must comply with the following rules:

- Must be **HTTPS** or a **deep link**
- **Cannot** be `localhost` or `127.0.0.1`

### Creating a Connect Token with OAuth Redirect

When creating a Connect Token, include the `oauthRedirectUri` in the options:

```bash
curl --request POST \
  --url https://api.pluggy.ai/connect_token \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "options": {
      "clientUserId": "your-user-id",
      "oauthRedirectUri": "https://your-own-url.com"
    }
  }'
```

> **Note**: If you create an item with a Connect Token and also specify the `oauthRedirectUri` at the time of item creation, the system will prioritize the `oauthRedirectUri` parameter provided at the item level.

### Example redirect URIs

| URI | Valid | Why |
|-----|-------|-----|
| `https://app.example.com/pluggy/callback` | Yes | HTTPS page in your application |
| `myapp://my-deep-link` | Yes | Deep link into a native app |
| `http://app.example.com/callback` | No | Plain HTTP is rejected |
| `http://localhost:3000/callback` | No | `localhost` and `127.0.0.1` are rejected |

Testing locally, use the deep-link scheme of your app or an HTTPS tunnel to your
machine — a `localhost` URI is refused when the token is created, not later.

## Browser-Specific Behavior

The OAuth flow behaves differently depending on the user's platform:

### Desktop Browsers

For **desktop browsers**, the authorization window will attempt to **close automatically** after the OAuth process is complete.

If closing the window is not possible, the user will be redirected to the provided `oauthRedirectUri`.

### Mobile Browsers

For **mobile browsers**, users will be **redirected to the `oauthRedirectUri`** after completing the OAuth authorization.

Some mobile browsers do not allow closing the OAuth authorization window after completion. To address this, you must provide an `oauthRedirectUri` in the Connect Token request, which will be used to redirect users back to your application.

## Handling the Redirect

Your application should be prepared to handle the redirection back to the `oauthRedirectUri`. When the user is redirected, you should:

1. Verify the connection status
2. Resume the user experience in your application
3. Handle any errors that may have occurred during the OAuth process

## Platform Considerations

### Web Applications

For web applications, the `oauthRedirectUri` should be a valid HTTPS URL that points to a page in your application that can handle the redirect and resume the connection flow.

### Mobile Applications (Native)

For native mobile applications, you can use a **deep link** as the `oauthRedirectUri`. This allows the OAuth flow to redirect back to your native app after the authorization is complete.

Ensure that your app is properly configured to handle the deep link scheme on both iOS and Android.

### React Native / Flutter

When using React Native or Flutter with the Pluggy Connect SDK, configure the `oauthRedirectUri` to use your app's deep link scheme. The SDK will handle the redirect and resume the connection flow within the widget.

## Backend integration, without the widget

If you create items from your own backend rather than through the widget, you do not
need a Connect Token at all: authenticate with your API key and pass
`oauthRedirectUri` to [items-create](/reference/items/items-create), exactly as you
would in the token's options.

```bash
curl --request POST \
  --url https://api.pluggy.ai/items \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "connectorId": 600,
    "parameters": {
      "user": "user-ok",
      "password": "password-ok"
    },
    "oauthRedirectUri": "https://your-own-url.com"
  }'
```

The response carries the OAuth URL to send the user to. When a value is given in both
places — the Connect Token's options and the item creation — the one on the item
wins, because it is the more specific of the two.

## Best Practices

- Always provide an `oauthRedirectUri` when your users may connect to institutions that use OAuth
- Use HTTPS URLs for web applications and deep links for native mobile apps
- Test the OAuth flow on both desktop and mobile browsers to ensure a smooth experience
- Handle edge cases where the authorization window cannot be closed automatically
- The `connectToken` is valid for **30 minutes only** -- the recommended usage is one token per connection