Procurando a documentação anterior?Acesse v1.docs.pluggy.ai
PluggyDocs

Credenciais e chaves da API

O que são o ID do cliente, o segredo do cliente e a chave da API, onde cada um pode estar, como armazenar e rotacionar o segredo do cliente e o que fazer quando uma credencial vaza.

Ver como Markdown

Cada aplicação no Dashboard possui suas próprias credenciais e, juntas, elas alcançam cada Item dessa aplicação. Esta página cobre onde cada uma pode estar e o que fazer quando uma é exposta.

As três credenciais#

CredencialO que éOnde pode estar
Client IDIdentifica a aplicação. Exibido no Dashboard a qualquer momento.Seu servidor. Não é um segredo por si só, mas é útil apenas junto com o client secret.
Client secretProva que você possui a aplicação. Exibido uma vez, quando é gerado.Apenas no seu servidor: um gerenciador de segredos ou uma variável de ambiente.
API keyCriada pelo seu servidor com POST /authAPI a partir do client ID e do secret. Tem acesso total a cada endpoint da Pluggy API.Apenas no seu servidor, na memória.

O front end nunca recebe nenhuma delas. Ele recebe um Connect Token, que seu backend cria para um usuário.

Armazene o client secret como uma senha#

  • Mantenha-o em um gerenciador de segredos ou em uma variável de ambiente do seu servidor. Nunca o comite, nunca o registre e nunca o coloque no código do front-end, em um aplicativo móvel, em um ticket ou em uma mensagem de chat.
  • Leia-o de um único lugar. Assim, uma rotação é uma atualização e um redeploy, não uma busca por repositórios.
  • Novos client secrets começam com pluggy_sk_ e carregam um checksum, para que scanners de segredos possam reconhecer um que acabe em um repositório. Veja Formato do client secret.
  • O segredo não pode ser visualizado novamente após o diálogo que o exibe ser fechado: nem no Dashboard e nem através da API. Se você perdê-lo, gere um novo.

Use a API key apenas do seu servidor#

  • Crie uma API key com POST /auth e reutilize-a até que expire, em vez de chamar POST /auth em cada solicitação. A vida útil e o limite de taxa de POST /authAPI estão em suas próprias páginas. Quando uma solicitação responde 401 porque a chave expirou, crie uma nova.
  • O SDK do Node.js (pluggy-sdk) cria a API key e a reutiliza para você.
  • Nunca envie uma API key para um navegador ou um aplicativo móvel, e nunca a registre: qualquer um que a possua tem o mesmo acesso que seu servidor até que expire.

Separe desenvolvimento, produção e inquilinos#

  • Uma aplicação por ambiente. Cada aplicação tem seu próprio client ID e client secret, então um segredo de desenvolvimento que vaza não alcança dados de produção. Veja Ambientes e produção.
  • Uma aplicação por inquilino, se você atender várias empresas: Itens só são acessíveis com as credenciais da aplicação sob a qual foram criados, então um segredo vazado ou rotacionado afeta um inquilino. Veja Uma aplicação, ou uma por cliente?.
  • Ir para produção rotaciona o segredo. Quando uma aplicação é movida para produção, seu segredo é rotacionado e o Dashboard pede a um Owner ou Admin para gerar um novo. Planeje o deploy do novo segredo para esse momento.

Rotacione o client secret#

Gere um novo segredo no Dashboard, na página da aplicação. Apenas os Owners e Admins de uma equipe podem fazer isso (veja Acesso da equipe).

  • O segredo atual para de funcionar imediatamente: a partir desse momento, POST /auth com ele falha. Qualquer serviço que precise de uma nova API key falha até que tenha o novo segredo, então saiba quais serviços o utilizam antes de clicar.
  • O novo segredo é exibido uma vez. Armazene-o em seu gerenciador de segredos antes de fechar o diálogo.
  • Gerar um novo segredo não revoga as API keys criadas antes dele. Elas continuam funcionando até expirarem.

Receita, com um script que verifica o novo segredo antes de você redeployar: Rotacione seu client secret.

Se uma credencial vazar#

Um client secret. Gere um novo imediatamente, faça o deploy e remova o valor antigo de onde quer que tenha sido exposto (histórico do repositório, logs, tickets). Em seguida, verifique o que foi feito com a aplicação enquanto o segredo era válido.

Uma API key, ou um segredo que foi usado para criar API keys que você não controla. Um novo client secret não interrompe essas chaves. Para cortá-las antes que expirem, um Owner pode desabilitar a aplicação no Dashboard: enquanto estiver desabilitada, a API rejeita suas API keys e Connect Tokens, e POST /auth responde 401 com CLIENT_DISABLED. Tudo que usa a aplicação para de funcionar, incluindo seus próprios serviços.

Reabilitar restaura API keys não expiradas

Desabilitar não revoga uma API key: bloqueia a aplicação. Quando você a habilita novamente, cada API key que ainda não expirou funciona novamente, incluindo uma vazada. Gere um novo client secret enquanto a aplicação estiver desabilitada e habilite-a apenas após as API keys criadas antes da rotação terem expirado.

Não protege contra#

  • Um segredo roubado de um servidor que você controla: a rotação limita quanto tempo ele permanece útil, mas seu gerenciador de segredos e o acesso ao servidor são seus para proteger.
  • Uma API key no código do front-end: rotacionar o segredo não a revoga. Mantenha as chaves no servidor.

Próximo: Connect Tokens.

Esta página foi útil?