Authentication

Pluggy uses two kinds of credentials, depending on where the request is made from:

• API Key -- used for server-side requests. It gives full access to all Pluggy API endpoints.
• Connect Token -- used from client-side applications (i.e. the Connect Widget). Its access is limited in scope.

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=).

So, for example, a newly created Connect Token can't be used to access information that was created previously with a different Connect Token.

For any other kind of request, such as retrieving all the Item related products data, configuring webhooks, and more, you'll need to do server-side requests using your API Key.

Create an API Key#

First, you'll need to authenticate with the Pluggy API, using your CLIENT_ID and CLIENT_SECRET, to create an API Key via POST /auth.

Note that these credentials are extremely sensitive, so please ensure to do this step in your secured server only.

This API Key expires after 2 hours and will give you full access to all Pluggy API endpoints.

Create a Connect Token#

Then, with your API Key, you'll have to make a call to POST /connect_token.

Important

The connectToken is valid for 30 minutes only. The recommended usage is 1-per-connection, so we suggest creating a new one each time you want to create or update an Item.

The usage of this Connect Token is identical to the API Key: simply pass it in the request authentication header, and the Pluggy API will take care of validating its scope.

Warning

Attempts to access detailed products data using a Connect Token (instead of an API Key) will result in a 403 Forbidden API response.

Configuring a Connect Token#

When you are creating a Connect Token you can provide some ItemOptions that will be passed down to all Items created using the same Connect Token.

{
  "webhookUrl": "https://example.com/webhook",
  "clientUserId": "My App UserId",
  "oauthRedirectUri": "https://pluggy.ai/demo",
  "avoidDuplicates": true
}

• webhookUrl: URL where you will receive all the events of the Items created with this token.
• clientUserId: You can use this field to link an Item with your user's identifier.
• oauthRedirectUri: URL to redirect the user to after the connect flow.
• avoidDuplicates: Avoids creating a new Item if there is already one with the same credentials.

Creating an Item#

To summarize, the flow to create an Item using a connectToken is:

1. Your server authenticates with CLIENT_ID and CLIENT_SECRET to get an API Key.
2. Your server creates a Connect Token and sends it to your client application.
3. Your client application uses the Connect Token to create the Item.

If you are using our Connect Widget, you'll only need to take care of providing the Connect Token -- the rest will be handled by us.

Keeping a connection reference#

When initializing the Connect Widget for your user, you may want to track which user the created connection belongs to. This can be done in a few ways:

• Connect Widget onSuccess event: When the connection is created and returned, you can recover the itemId to store on your side.
• Webhooks: After the Item has been successfully created and synchronized, you will receive events. See Webhooks.
• Linking your user identifier with an Item: If you need to link the Item to your user, you can store a reference on our Item by using the clientUserId. This value can be provided when creating the connectToken or when creating an Item directly through the Items endpoint.