O que é uma chave de API?

O que é uma chave de API

O que é uma chave de API? Guia simples com checklist de segurança | We.Inc

O que é uma chave de API, como ela difere de uma senha ou de um token OAuth, onde guardá-la, como restringir e trocar e o que fazer no minuto em que uma vazar.

Uma chave de API é uma string secreta longa que um programa envia em cada requisição para provar qual conta está chamando um serviço, como um provedor de pagamentos, mapas ou email. Trate a maioria das chaves como uma senha: deixe-as num servidor, nunca no código do site, limite o que elas podem fazer e substitua-as se forem expostas.

Chave de API, token OAuth e senha comparados

Chave de API
Token de acesso OAuth
Senha

Quem usa
O seu próprio código ou servidor
Um app agindo por um usuário que o aprovou
Uma pessoa fazendo login

Como você obtém
Copia do painel do provedor
Emitido depois que o usuário clica em Permitir
Escolhida pela pessoa

Validade típica
Até você trocar ou apagar
Curta, depois renovado
Até ser alterada

Escopo
O que você liberou ao criá-la
As permissões que o usuário concedeu
Tudo o que a conta pode fazer

Se você tem um site ou uma loja, encontra chaves de API sempre que conecta um serviço: pagamentos, mapas, email, uma ferramenta de formulários ou um agente de IA. A maioria é secreta, algumas são feitas para ser públicas, e confundir uma com a outra é como acontecem contas altas e vazamentos de dados. Cole uma chave no inspetor abaixo para ver de que tipo ela parece ser; ele roda inteiro no seu navegador e não envia nada para lugar nenhum.

Você cria a chave no painel do provedor e a copia uma vez; muitos provedores nunca mais a mostram.
O seu servidor a guarda numa variável de ambiente ou nas configurações de segredos da hospedagem.
Cada requisição ao provedor leva a chave, normalmente num header Authorization.
O provedor consulta a chave, verifica o que ela tem permissão para fazer e responde ou recusa.

Nunca cole uma chave secreta em código front-end, num repositório público, num chat de suporte ou num email.
Use chaves restritas quando houver. A Stripe, por exemplo, recomenda chaves restritas que tenham só as permissões de que uma integração precisa.
Adicione restrições como sites permitidos, endereços IP ou APIs específicas, para que uma chave roubada valha menos.
Apague as chaves que não usa mais e troque as outras periodicamente, e também quando alguém com acesso sair.
Mantenha chaves de teste e de produção separadas. Muitos provedores as indicam no prefixo, como sk_test_ e sk_live_.

Perguntas frequentes

Uma chave de API é o mesmo que uma senha?

As duas são segredos, mas a senha é para uma pessoa fazer login, enquanto a chave de API é para um software chamar um serviço. As chaves são longas e aleatórias, normalmente limitadas a certas ações, e podem ser substituídas sem mudar o login de ninguém.

Posso colocar uma chave de API no JavaScript do meu site?

Só se o provedor disser que aquele tipo de chave pode ser exposto. As chaves publicáveis da Stripe, que começam com pk_, são feitas para código front-end; as secretas e as restritas não. Tudo o que está no navegador pode ser lido por qualquer visitante.

Onde devo guardar as chaves de API?

Num cofre de segredos ou nas configurações de variáveis de ambiente da sua hospedagem. A Stripe e o Google dizem para não colocar chaves no código-fonte nem fazer commit delas em repositórios.

O que fazer se a minha chave de API vazou?

Revogue ou troque a chave na hora no painel do provedor e depois coloque a nova chave nas configurações do seu servidor. A orientação do GitHub sobre segredos detectados é trocar a credencial afetada imediatamente; só limpar o histórico não torna segura uma chave ativa.

Chave de API ou OAuth?

Use uma chave de API quando o seu próprio servidor conversa com um serviço na sua própria conta. Use OAuth quando o seu app precisa agir por outras pessoas nas contas delas, porque assim cada uma concede e pode revogar o acesso por conta própria.

Chaves públicas e chaves secretas

Alguns serviços emitem um par. Uma chave publicável identifica a sua conta a partir do navegador, mas não consegue fazer nada sensível, enquanto a chave secreta no seu servidor pode cobrar cartões ou ler dados. A documentação da Stripe indica apenas a chave publicável como segura para expor.
Mesmo assim, vale restringir uma chave de navegador. A orientação do Google Cloud é adicionar restrições de chave de API, que limitam as formas de uso da chave e assim reduzem o estrago se alguém a copiar.

Checklist para chave vazada

Primeiro, troque ou apague a chave no painel do provedor. Segundo, coloque a nova chave em todos os lugares que usavam a antiga. Terceiro, confira nos logs de uso do provedor chamadas que você não fez. Quarto, descubra como ela vazou, como um arquivo commitado ou um bundle front-end, e feche essa brecha.

Usar uma chave com segurança a partir de um servidor

A chave fica numa variável de ambiente no servidor. O navegador chama o seu próprio endpoint, que adiciona a chave e chama o provedor.

.env (nunca commitado)

Apenas valores de exemplo. Adicione .env ao .gitignore para que ele nunca chegue ao seu repositório.

Uma rota de servidor bem pequena. O segredo é lido no servidor e nunca enviado ao navegador.

Inspetor de chave de API

Cole uma chave ou só os primeiros caracteres dela. A verificação roda apenas no seu navegador; mesmo assim, prefira uma chave de teste ou um valor fictício a um segredo de produção.

Chave para inspecionar

Chave publicável da Stripe

Chave secreta da Stripe

Chave restrita da Stripe

Token do Notion

Segredo de assinatura de webhook (prefixo whsec_)

Nenhum prefixo conhecido. Trate como secreta, a não ser que o provedor diga o contrário.

Feita para código front-end, segundo o provedor.

Secreta: mantenha num servidor, nunca numa página web.

Chave de modo de teste ou sandbox.

Chave de modo de produção: dinheiro real ou dados reais.

Tamanho: {n} caracteres

Aleatoriedade aproximada, se gerada aleatoriamente: {n} bits

Parece curta para um segredo. Cerca de {n} bits ou mais é uma meta aproximada sensata.

O que é uma chave de API?