# 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 Móvel) para autenticar-se 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 da 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 do 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 da 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 no 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 da 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 na 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 na 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

<Callout variant="warning" title="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.
</Callout>

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