# Autenticação

## Visão Geral

Ao conectar-se ao Pluggy a partir de uma aplicação do lado do cliente (ou seja, o Connect Widget), exigimos o uso de um **Connect Token**. O acesso ao Connect Token é limitado apenas aos dados do recurso Item gerado (`GET /items/:id`), e um acesso reduzido aos dados das Contas recuperadas (`GET /accounts?itemId`).

Um Connect Token recém-criado não pode ser usado para acessar informações que foram criadas anteriormente com um Connect Token diferente.

## Connect Token

Um Connect Token é um token de acesso limitado que:

- **Expira em 30 minutos** após a criação
- Destina-se a ser usado por **aplicações frontend** (Web ou Mobile) para autenticar com o Pluggy
- É especialmente útil para usuários finais conectarem suas contas através do widget Pluggy Connect
- Tem visibilidade apenas para as conexões que foram criadas usando este token

## Fluxo de Autenticação

Tanto as Chaves de API quanto os Connect Tokens podem ser recuperados usando o `CLIENT_ID` e `CLIENT_SECRET` fornecidos no [Dashboard](https://dashboard.pluggy.ai).

![Fluxo de autenticação Pluggy Connect](/docs/images/connect-flow-diagram.jpg)

O processo de autenticação funciona da seguinte forma:

### 1. Autenticação do Backend

Primeiro, autentique-se com a API do Pluggy usando seu `CLIENT_ID` e `CLIENT_SECRET` para criar uma Chave de API:

```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. Criar um Connect Token

Configure um endpoint em seu backend que obtém e fornece um Connect Token, que concede autorização ao Pluggy Connect para acessar a API do Pluggy em nome de sua aplicação:

```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"
    }
  }'
```

Ao criar um Connect Token, você pode fornecer algumas `ItemOptions` que serão passadas para todos os itens criados usando o mesmo token:

| Parâmetro | Descrição |
|-----------|-------------|
| `clientUserId` | Um identificador para o usuário em sua aplicação, útil para rastreabilidade |
| `webhookUrl` | URL onde o Pluggy enviará notificações de webhook |
| `oauthRedirectUri` | URI para redirecionar usuários após o processo de OAuth |
| `avoidDuplicates` | Se deve evitar a criação de itens duplicados |

### 3. Integração do Widget Frontend

Use o Connect Token em sua aplicação frontend para inicializar o widget Pluggy Connect:

```javascript
import PluggyConnect from 'pluggy-connect-sdk';

const pluggyConnect = new PluggyConnect({
  connectToken: 'your-connect-token',
  onSuccess: (itemData) => {
    console.log('Conexão bem-sucedida!', itemData);
  },
  onError: (error) => {
    console.error('Erro de conexão:', error);
  },
});

pluggyConnect.init();
```

Ou com 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)}
    />
  );
}
```

## Aviso de Segurança

> **Importante**: Não armazene `clientId` e `clientSecret` no frontend. Se essas informações forem visíveis no código da sua página, um atacante pode roubar todos os dados bancários dos seus usuários.

Você precisa criar um endpoint de backend que gera um Connect Token para cada usuário que visita sua página. Este Connect Token tem permissões e duração restritas por razões de segurança.

A arquitetura adequada é:

1. **Backend** gera o Connect Token usando `CLIENT_ID` e `CLIENT_SECRET` (mantidos seguros no servidor)
2. **Frontend** recebe apenas o Connect Token de escopo limitado
3. **Frontend** usa o Connect Token com o Pluggy Connect Widget