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:

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:

Verify the connection status
Resume the user experience in your application
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.

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-createAPI, exactly as you would in the token's options.

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