# 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](https://dashboard.pluggy.ai).

![Pluggy Connect authentication flow](/docs/images/connect-flow-diagram.jpg)

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:

```bash
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:

```bash
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:

| Parameter | Description |
|-----------|-------------|
| `clientUserId` | An identifier for the user in your application, useful for traceability |
| `webhookUrl` | URL where Pluggy will send webhook notifications |
| `oauthRedirectUri` | URI to redirect users after OAuth process |
| `avoidDuplicates` | Whether to avoid creating duplicate items |

### 3. Frontend Widget Integration

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

```javascript
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:

```jsx
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