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.

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.

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.

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