Authentication

Overview#

When connecting to Pluggy from a client-side application (i.e. the Connect Widget), we require the use of a Connect Token. The Connect Token access is limited to only the generated Item resource data (GET /items/:id), and a reduced access to the data of the recovered Accounts (GET /accounts?itemId).

A newly created Connect Token can't be used to access information that has been created previously with a different Connect Token.

Connect Token#

A Connect Token is a limited-access token that:

• Expires 30 minutes after creation
• Is meant to be used by frontend applications (Web or Mobile) to authenticate with Pluggy
• Is specially useful for end-users to connect their accounts through the Pluggy Connect widget
• Has visibility only for the connections that were created using this token

Authentication Flow#

Both API Keys and Connect Tokens can be recovered using the CLIENT_ID and CLIENT_SECRET provided in the Dashboard.

The authentication process works as follows:

1. Backend Authentication#

First, authenticate with the Pluggy API using your CLIENT_ID and CLIENT_SECRET to create an API Key:

curl --request POST \
  --url https://api.pluggy.ai/auth \
  --header 'Content-Type: application/json' \
  --data '{
    "clientId": "YOUR_CLIENT_ID",
    "clientSecret": "YOUR_CLIENT_SECRET"
  }'

2. Create a Connect Token#

Set up an endpoint on your backend that obtains and provides a Connect Token, which grants Pluggy Connect authorization to access the Pluggy API on behalf of your application:

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",
      "webhookUrl": "https://www.myapi.com/notifications"
    }
  }'

When creating a Connect Token you can provide some ItemOptions that will be passed down to all items created using the same token:

3. Frontend Widget Integration#

Use the Connect Token in your frontend application to initialize the Pluggy Connect widget:

import PluggyConnect from 'pluggy-connect-sdk';
 
const pluggyConnect = new PluggyConnect({
  connectToken: 'your-connect-token',
  onSuccess: (itemData) => {
    console.log('Connection successful!', itemData);
  },
  onError: (error) => {
    console.error('Connection error:', error);
  },
});
 
pluggyConnect.init();

Or with React:

import { PluggyConnect } from 'react-pluggy-connect';
 
function App() {
  return (
    <PluggyConnect
      connectToken="your-connect-token"
      onSuccess={({ item }) => console.log(item.id)}
      onError={({ message }) => console.error(message)}
    />
  );
}

Security Warning#

Important: Do not store clientId and clientSecret in the frontend. If this information is visible in your page's code, an attacker can steal all of your user's banking data.

You need to create a backend endpoint that generates a Connect Token for every user that visits your page. This Connect Token has restricted permissions and duration for security reasons.

The proper architecture is:

1. Backend generates the Connect Token using CLIENT_ID and CLIENT_SECRET (kept secure on the server)
2. Frontend receives only the limited-scope Connect Token
3. Frontend uses the Connect Token with the Pluggy Connect Widget