OAuth Support Guide

Fast Integration

TL;DR Guide

1. Set Up Redirect URI:

   • Define an oauthRedirectUri to handle redirections after the OAuth process. This URI must be HTTPS and cannot be localhost.

2. Request Connect Token:

   • Use the following cURL command to request a connect token. Replace"https://your-own-url.com" with your actual user ID and redirect URI:
   
   
   Shell

   curl --request POST \
        --url https://api.pluggy.ai/connect_token \
        --header 'accept: application/json' \
        --header 'content-type: application/json' \
        --data '
   {
     "options": {
       "oauthRedirectUri": "https://your-own-url.com"
     }
   }
   '
   

4. Handle OAuth Flow:
   1. Redirect users to the OAuth URL provided by the API.
   2. Ensure your application is set to handle the redirection back to the oauthRedirectUri.
5. Special Considerations:
   1. Be aware of browser-specific behaviors. For desktop browsers, the authorization window will attempt to close automatically. For mobile browsers, users will be redirected to the oauthRedirectUri.

This guide provides a quick overview of the necessary steps for integrating OAuth. For detailed information and troubleshooting, refer to the full documentation below.

What is OAuth?

OAuth (Open Authorization) is an open standard for access delegation, commonly used as a way to grant websites or applications limited access to a user's information without exposing passwords. It is a secure and convenient way to handle authorization, providing an interface for applications to connect to third-party services on behalf of a user.

Why Use OAuth?

Familiar and Reliable User Experience

OAuth enables users to link their accounts through reputable services they already know, fostering a sense of security and reliability. This familiarity with the authorization process helps build user confidence in the safety and legitimacy of the connection.

Improved Connection Stability

Utilizing OAuth allows applications to establish and maintain a stable connection with third-party services. The ability to refresh OAuth tokens automatically means that users can access resources seamlessly without needing to log in repeatedly, ensuring consistent and uninterrupted service access.

Common Issues with OAuth

One challenge with OAuth is handling the authorization flow on different devices and browsers. For example, some mobile browsers do not allow closing the OAuth authorization window after the process is complete, causing potential confusion for users.

Setting Up the Connect Token

To address this issue, we require developers to provide an oauthRedirectUri in the connect token request. This URI is used to redirect users back to your application after they have completed the OAuth process with the financial institution.

Here’s how you can create a connect token with the oauthRedirectUri:

Basic Example (Without Redirect URI)

curl --request POST \
     --url https://api.pluggy.ai/connect_token \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "options": {
    "clientUserId": "your-user-id"
  }
}
'

 

Example with Redirect URI

curl --request POST \
     --url https://api.pluggy.ai/connect_token \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "options": {
    "clientUserId": "your-user-id",
    "oauthRedirectUri": "https://your-url.com"
  }
}
'

Special Considerations for Mobile and Desktop Browsers

In desktop browsers, after completing the OAuth process, we will attempt to close the authorization window. If closing the window is not possible, we will redirect the user to the provided oauthRedirectUri. This flow is particularly designed for mobile users, where browser limitations might restrict window management.

Example OAuth URLs

• https://pluggy.ai
• https://my-subdomain.pluggy.ai

http, or localhost urls are not allowed

Backend Integration

Step-by-Step Guide:

Instead of using the connect token, you can directly use your api_key in your backend integration. Follow the steps below for a smooth integration:

1. Create the Item Using API Key:

   • Use your api_key to authenticate and create an item with the POST /item endpoint.
   • You can specify the oauthRedirectUri parameter at this step, just as you would in the connect token request.

2. Example Request:

   Shell

   curl --request POST \
        --url https://api.pluggy.ai/items \
        --header 'accept: application/json' \
        --header 'content-type: application/json' \
        --header 'Authorization: Bearer your-api-key' \
        --data '
   {
     "connectorId": 600,
     "parameters": {
       "username": "username",
       "password": "password"
     },
      "oauthRedirectUri": "https://your-own-url.com"
   }
   '
   

FAQ

What Happens if I Specify oauthRedirectUri in Both Connect Token and Item?

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, as it is more specific.