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 /authAPI | 2 horas | Cada endpoint. Somente do lado do servidor. |
| Connect Token | POST /connect_tokenAPI | 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#
Resposta 200:
clientId e clientSecret vêm do Dashboard. 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 taxaAPI, e solicitar uma chave por chamada é a maneira usual de atingi-lo.
Connect Token#
Resposta 200:
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. |
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}API.
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}API para seu próprio Item e GET /accounts?itemId=API 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#
- Seu servidor chama
POST /authcomclientIdeclientSecrete mantém a API Key. - Seu servidor chama
POST /connect_tokencom essa chave e entrega oaccessTokenao seu cliente. - Seu cliente — o Connect Widget ou sua própria interface — cria ou atualiza o Item com o token.
- Seu servidor lê os dados do Item com a API Key.
Leia o guia: Authentication.