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 secret do cliente e a chave da API, onde cada um pode estar, como armazenar e rotacionar o secret do cliente e o que fazer quando uma credencial vaza.

Ver como Markdown

Toda 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 delas é 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 em código de front-end, um aplicativo móvel, um ticket ou 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 secret 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ê o perder, 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 requisição. A vida útil e o limite de taxa de POST /authAPI estão em suas próprias páginas. Quando uma requisição responde 401 porque a chave expirou, crie uma nova.
  • O SDK 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.

Restringir os IPs que podem usá-las#

Dê à aplicação uma lista de IPs permitidos e POST /auth, e cada requisição feita com suas API keys será aceita apenas dos IPs do seu servidor. Um secret ou API key que vazar não poderá ser usado de nenhum outro lugar. Requisições feitas com um Connect Token não são restritas, então o Pluggy Connect continua funcionando nos dispositivos dos seus usuários.

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 secret de desenvolvimento que vazar 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 secret vazado ou rotacionado afeta apenas um inquilino. Veja Uma aplicação, ou uma por cliente?.
  • Ir para produção rotaciona o secret. Quando uma aplicação é movida para produção, seu secret é rotacionado e o Dashboard pede a um Owner ou Admin para gerar um novo. Essa rotação nunca mantém o secret anterior funcionando, então planeje o deploy do novo secret para aquele momento.

Rotacione o client secret#

Clique em Gerar novo secret na página da aplicação no Dashboard. Apenas Owners e Admins de uma equipe podem fazer isso (veja Acesso da equipe).

A confirmação tem a opção Manter o secret anterior funcionando por 24 horas, marcada por padrão:

  • Marcada: o novo secret funciona imediatamente, e o anterior continua funcionando com POST /auth por 24 horas, depois para por conta própria. Uma rotação não precisa de downtime: gere o novo secret, implemente-o em cada serviço, e você está feito.
  • Desmarcada: o secret anterior para de funcionar imediatamente. Qualquer serviço que precise de uma nova API key falha até que tenha o novo secret. Use isso quando o secret pode ter sido exposto.

Enquanto o secret anterior ainda for válido, a página da aplicação mostra quando ele para de funcionar e um botão Revogar agora que encerra imediatamente. Clique nele assim que cada serviço usar o novo secret, ou deixe-o expirar.

  • Uma aplicação tem no máximo dois secrets válidos: o atual e o anterior. Gerar outro secret durante essas 24 horas invalida o mais antigo, e gerar um sem a opção invalida todos os secrets anteriores.
  • A opção não é oferecida quando o Pluggy requer um novo secret por segurança, como após a aplicação ser movida para produção ou após o Pluggy rotacionar um secret encontrado exposto.
  • O novo secret é exibido uma vez. Armazene-o em seu gerenciador de segredos antes de fechar o diálogo.
  • Gerar um novo secret, ou clicar em Revogar agora, não revoga as API keys criadas antes dele. Elas continuam funcionando até expirarem.

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

Se uma credencial vazar#

Um client secret. Gere um novo imediatamente com Manter o secret anterior funcionando por 24 horas desmarcado, para que o secret vazado pare de funcionar de imediato (se você já gerou um mantendo-o, clique em Revogar agora). Implemente o novo secret e remova o valor antigo de onde quer que tenha sido exposto (histórico do repositório, logs, tickets). Depois, verifique o que foi feito com a aplicação enquanto o secret era válido.

Uma API key, ou um secret que foi usado para criar API keys que você não controla. Um novo client secret não para essas chaves. Para cortá-las antes que expirem, um Owner pode desativar a aplicação no Dashboard: enquanto estiver desativada, a API rejeita suas API keys e Connect Tokens, e POST /auth responde 401 com CLIENT_DISABLED. Tudo que usa a aplicação para.

Se a aplicação tiver uma lista de IPs permitidos, uma API key ou secret vazado só funciona dos IPs nela, o que lhe dá tempo. Isso não substitui a rotação do secret.

Reabilitar restaura API keys não expiradas

Desativar 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 desativada e habilite-a apenas após as API keys criadas antes da rotação terem expirado.

Não protege contra#

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

Próximo: Lista de IPs permitidos.

Esta página foi útil?