# Autenticação

Cada solicitação carrega uma credencial no cabeçalho `X-API-KEY`. Existem dois tipos, emitidos por dois endpoints, e a diferença entre eles é o escopo.

| Credencial | Emitido por | Dura | Atinge |
| --- | --- | --- | --- |
| **API Key** | [`POST /auth`](/reference/auth/auth-create) | 2 horas | Cada endpoint. Somente do lado do servidor. |
| **Connect Token** | [`POST /connect_token`](/reference/auth/connect-token-create) | 30 minutos | O Item para o qual foi emitido e uma visão reduzida de suas Contas. Seguro para entregar a um cliente. |

## API Key

```http
POST https://api.pluggy.ai/auth
Content-Type: application/json

{ "clientId": "…", "clientSecret": "…" }
```

Resposta `200`:

```json
{ "apiKey": "…" }
```

`clientId` e `clientSecret` vêm do [Dashboard](https://dashboard.pluggy.ai). Eles identificam sua aplicação, então `POST /auth` deve estar no seu servidor e em nenhum outro lugar. Um `401` com `codeDescription` `CLIENT_KEYS_UNAUTHORIZED` significa que o par está errado; `CLIENT_DISABLED` significa que a aplicação está desligada.

A chave expira **2 horas** após ser emitida. Reutilize-a até lá — `POST /auth` tem seu próprio [limite de taxa](/reference/rate-limits), e solicitar uma chave por chamada é a maneira usual de atingi-lo.

## Connect Token

```http
POST https://api.pluggy.ai/connect_token
X-API-KEY: {apiKey}
Content-Type: application/json

{
  "itemId": "…",
  "options": {
    "clientUserId": "…",
    "webhookUrl": "https://…",
    "oauthRedirectUri": "https://…",
    "avoidDuplicates": true
  }
}
```

Resposta `200`:

```json
{ "accessToken": "…" }
```

Tudo no corpo é opcional. `itemId` limita o token a um Item existente, para uma atualização. `options` são aplicadas a cada Item criado com o token:

| Opção | Efeito |
| --- | --- |
| `clientUserId` | Seu identificador para o usuário final, armazenado no Item e ecoado em cada webhook `item/*`. |
| `webhookUrl` | Onde os eventos desses Itens são entregues. |
| `oauthRedirectUri` | Onde o usuário aterrissa após um fluxo de conexão OAuth. |
| `avoidDuplicates` | Não criar um segundo Item para credenciais que já possuem um. |

<Callout variant="warning" title="As opções vão dentro de options">
As únicas chaves lidas na raiz do corpo são `itemId` e `options`. Um `clientUserId` enviado na raiz é descartado — a chamada ainda retorna `200`, e os Itens acabam com `clientUserId: null`. Preencha um Item afetado com [`PATCH /items/{id}`](/reference/items/items-update).
</Callout>

O token expira **30 minutos** após ser emitido. Emita um por conexão: um novo cada vez que você criar ou atualizar um Item.

## Escopo

Um Connect Token é enviado exatamente como uma API Key, em `X-API-KEY`. Ele pode chamar [`GET /items/{id}`](/reference/items/items-retrieve) para seu próprio Item e [`GET /accounts?itemId=`](/reference/account/accounts-list) com uma visão reduzida dos dados; qualquer outra coisa retorna `403`. Um token emitido para um Item não pode ler outro, incluindo Itens criados anteriormente com um token diferente.

## O fluxo, do início ao fim

1. Seu servidor chama `POST /auth` com `clientId` e `clientSecret` e mantém a API Key.
2. Seu servidor chama `POST /connect_token` com essa chave e entrega o `accessToken` ao seu cliente.
3. Seu cliente — o [Connect Widget](/docs/connect-widget/introduction) ou sua própria interface — cria ou atualiza o Item com o token.
4. Seu servidor lê os dados do Item com a API Key.

Leia o guia: [Authentication](/docs/authentication).