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#
| Credencial | O que é | Onde pode estar |
|---|---|---|
| Client ID | Identifica 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 secret | Prova 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 key | Criada 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 /authe reutilize-a até que expire, em vez de chamarPOST /authem cada solicitação. A vida útil e o limite de taxa dePOST /authAPI estão em suas próprias páginas. Quando uma solicitação responde401porque 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 /authcom 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.
