# Autenticação

Pluggy usa dois tipos de credenciais, dependendo de onde a solicitação é feita:

- **API Key** -- usada para solicitações do lado do servidor. Ela dá acesso total a todos os endpoints da API do Pluggy.
- **Connect Token** -- usada a partir de aplicações do lado do cliente (ou seja, o [Connect Widget](/docs/connect-widget/introduction)). Seu acesso é limitado em escopo.

O acesso do Connect Token é limitado apenas aos dados do recurso Item gerado ([GET /items/:id](/reference/items-retrieve)), e um acesso reduzido aos dados das Contas recuperadas ([GET /accounts?itemId=](/reference/accounts-list)).

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

Para qualquer outro tipo de solicitação, como recuperar todos os dados de produtos relacionados ao Item, configurar webhooks, [e mais](/reference/auth), você precisará fazer solicitações do lado do servidor usando sua API Key.

## Criar uma API Key

Primeiro, você precisará se autenticar com a API do Pluggy, usando seu `CLIENT_ID` e `CLIENT_SECRET`, para [criar uma API Key](/reference/auth-create) via `POST /auth`.

*Observe que essas credenciais são extremamente **sensíveis**, então, por favor, certifique-se de fazer esta etapa apenas em seu servidor seguro.*

Esta API Key expira após 2 horas e lhe dará acesso total a todos os endpoints da API do Pluggy.

## Criar um Connect Token

Em seguida, com sua API Key, você terá que fazer uma chamada para [POST /connect_token](/reference/connect-token-create).

> **Importante**
>
> O `connectToken` é válido apenas por 30 minutos.
> O uso recomendado é 1 por conexão, então sugerimos criar um novo sempre que você quiser criar ou atualizar um Item.

O uso deste **Connect Token** é idêntico ao da **API Key**: basta passá-lo no cabeçalho de autenticação da solicitação, e a API do Pluggy cuidará de validar seu escopo.

> **Aviso**
>
> Tentativas de acessar dados detalhados de produtos usando um Connect Token (em vez de uma API Key) resultarão em uma resposta da API `403 Forbidden`.

### Configurando um Connect Token

Ao criar um Connect Token, você pode fornecer algumas `ItemOptions` que serão passadas para todos os Itens criados usando o mesmo Connect Token. **Elas devem ser enviadas aninhadas dentro do atributo `options` do corpo da solicitação** -- este é o payload completo:

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

- `webhookUrl`: URL onde você receberá todos os eventos dos Itens criados com este token.
- `clientUserId`: Você pode usar este campo para vincular um Item ao identificador do seu usuário.
- `oauthRedirectUri`: URL para redirecionar o usuário após o fluxo de conexão.
- `avoidDuplicates`: Evita criar um novo Item se já houver um com as mesmas credenciais.

O único outro atributo aceito na raiz do corpo é `itemId`, usado quando o widget atualiza um Item existente (veja [Atualizando um Item](/docs/connect-widget/updating-item)).

> **Aviso**
>
> Qualquer outra propriedade enviada na **raiz** do corpo é ignorada. Enviar `clientUserId`
> na raiz em vez de dentro de `options` ainda retorna `200 OK`, mas o valor é
> descartado: os Itens criados com esse token terão `clientUserId: null`, e o
> campo também será `null` nos payloads de webhook `item/created`, `item/updated` e `item/error`.
>
> ```json
> // ❌ Errado -- clientUserId é descartado silenciosamente
> { "clientUserId": "Meu App UserId", "options": { "avoidDuplicates": true } }
>
> // ✅ Correto
> { "options": { "clientUserId": "Meu App UserId", "avoidDuplicates": true } }
> ```
>
> Se você já tiver Itens criados dessa forma, pode preencher o valor com
> [PATCH /items/{id}](/reference/items-update).

## Criando um Item

Para resumir, o fluxo para criar um [Item](/docs/connections/item) usando um `connectToken` é:

1. Seu servidor se autentica com `CLIENT_ID` e `CLIENT_SECRET` para obter uma API Key.
2. Seu servidor cria um Connect Token e o envia para sua aplicação cliente.
3. Sua aplicação cliente usa o Connect Token para criar o Item.

Se você estiver usando nosso [Connect Widget](/docs/connect-widget/introduction), você só precisará se preocupar em fornecer o Connect Token -- o resto será tratado por nós.

### Mantendo uma referência de conexão

Ao inicializar o Connect Widget para seu usuário, você pode querer rastrear a qual usuário a conexão criada pertence. Isso pode ser feito de algumas maneiras:

- **Evento `onSuccess` do Connect Widget**: Quando a conexão é criada e retornada, você pode recuperar o `itemId` para armazenar do seu lado.
- **Webhooks**: Após o Item ter sido criado e sincronizado com sucesso, você receberá eventos. Veja [Webhooks](/docs/developer-tools/webhooks-ref).
- **Vinculando seu identificador de usuário a um Item**: Se você precisar vincular o Item ao seu usuário, pode armazenar uma referência em nosso Item usando o `clientUserId`. Este valor pode ser fornecido ao criar o `connectToken` ou ao criar um Item diretamente através do [endpoint de Itens](/docs/connections/item).