Toda integração com o Stripe começa com a mesma pergunta: qual chave vai onde? O Stripe te entrega uma chave publicável, uma chave secreta e a opção de criar chaves restritas, cada uma em versão de teste e de produção. Coloque a errada no lugar errado e você ou vaza a capacidade de movimentar dinheiro ou perde uma tarde com um 401. Este guia cobre o que cada chave de API do Stripe faz, onde ela fica, como enviar uma primeira requisição em modo de teste e como manter a chave de produção fora de qualquer coisa compartilhada. Para o conceito geral primeiro, comece com o que é uma chave de API. Tudo abaixo segue a documentação de chaves de API do Stripe, verificada em setembro de 2026.
Onde ficam suas chaves de API do Stripe no Dashboard
Abra a página de chaves de API em dashboard.stripe.com/apikeys. Ela fica em Developers no Dashboard e mostra as chaves da conta ou sandbox que você está visualizando. Um botão alterna entre o modo sandbox e o modo de produção, e a lista de chaves muda junto.
A página tem duas listas:
- Chaves padrão contêm sua chave publicável e sua chave secreta.
- Chaves restritas contêm quaisquer chaves que você criou com permissões segmentadas.
A visibilidade varia conforme o modo. Em um sandbox você pode revelar qualquer chave a qualquer momento. No modo de produção, uma chave secreta que você mesmo cria é exibida uma vez, na criação. Copie-a para o seu cofre antes de fechar a caixa de diálogo; perdê-la significa rotacioná-la. Apenas as chaves padrão geradas pelo Stripe podem ser reveladas novamente no modo de produção.
Uma coisa que a página não mostra: os segredos de assinatura de webhook. Eles ficam em Webhooks, por endpoint, e não são chaves de API de forma alguma.
Chaves publicáveis vs. secretas
Os nomes descrevem o limite de confiança.
| Chave | Prefixo | Seguro expor | O que ela pode fazer |
|---|---|---|---|
| Publicável | pk_test_ / pk_live_ |
Sim | Identificar sua conta, criar tokens e PaymentMethods a partir de dados de cartão no Stripe.js, Elements e SDKs móveis |
| Secreta | sk_test_ / sk_live_ |
Não | Tudo: criar cobranças, emitir reembolsos, ler dados de clientes, disparar repasses |
| Restrita | rk_test_ / rk_live_ |
Não | Apenas os recursos e permissões que você conceder |
Uma chave publicável pertence ao navegador ou ao aplicativo móvel. Ela transforma um número de cartão em um token e pouco mais. Não consegue criar uma cobrança nem ler dados da conta, então distribuí-la em código de front-end é esperado.
Uma chave secreta pertence ao seu servidor e a nenhum outro lugar. A orientação do Stripe mudou: a documentação agora diz que eles “não recomendam usar chaves secretas para novos casos de uso” e apontam para chaves restritas. A chave secreta irrestrita ainda funciona, mas trate-a como situação de emergência, não como padrão.
Chaves de modo de teste vs. produção
O Stripe opera dois mundos separados, cada um com seu próprio conjunto de chaves. As chaves de teste (a documentação mais recente chama o lado de teste de sandbox, embora os prefixos ainda digam _test_) retornam objetos simulados: clientes falsos, PaymentIntents falsos, cartões de teste que aprovam ou recusam sob comando, nenhum dinheiro real. As chaves de produção acessam as redes de cartão e movimentam fundos reais.
A separação é estrita. Um cliente criado com sk_test_ não existe para fins de sk_live_, e vice-versa. O código de erro do Stripe para cruzar os fluxos, livemode_mismatch, diz claramente: “Chaves de API, requisições e objetos de modo de teste e de produção só estão disponíveis dentro do modo correspondente.”
Duas regras práticas decorrem disso:
- Construa e teste inteiramente contra
sk_test_ourk_test_. O Stripe recomenda um sandbox geral separado para novas integrações, para que suas configurações e dados permaneçam isolados. - Mudar para produção é uma alteração de configuração, não de código. Seu servidor lê a chave de uma variável de ambiente ou de um cofre, e entrar em produção significa alterar esse valor.
Toda resposta da API inclui um booleano livemode. Faça asserções sobre ele em seus testes; é a proteção mais barata contra um deploy com a chave errada.
Chaves restritas e privilégio mínimo
Uma chave de API restrita (o Stripe abrevia como RAK) é uma chave secreta com uma máscara de permissões. Ao criar uma, você escolhe uma permissão para cada grupo de recursos: None, Read ou Write. Tudo tem como padrão None. Write inclui Read, e o mapeamento para HTTP é simples: GET precisa de Read, POST e DELETE precisam de Write.
Para criar uma, clique em Create restricted key na página de chaves de API, escolha um conjunto de permissões pré-configurado ou comece do zero, dê um nome, defina as permissões e conclua o prompt de dois fatores. Assim como uma chave secreta criada por você mesmo no modo de produção, você vê o valor uma vez.
O guia de chaves restritas sugere uma chave por serviço: um serviço de cobrança recebe Write em Invoices e Customers, um job de relatórios recebe Read em Charges e Disputes. Se um serviço for comprometido, o atacante fica limitado às permissões daquela chave. Uma chave somente leitura de disputas não consegue criar uma cobrança nem tocar em um repasse.
Dê a uma nova chave permissões amplas em um sandbox, execute sua suíte de testes, depois abra os logs de requisição da chave (menu de overflow, View request logs) e remova toda permissão que não teve tráfego. O Stripe também permite marcar chaves destinadas a agentes de IA autônomos, para que fiquem sujeitas a regras de aprovação para repasses e reembolsos; use esse caminho em vez de uma chave secreta comum.
Sua primeira requisição com curl e Python
O Stripe autentica com HTTP Basic Auth: a chave é o nome de usuário e a senha fica vazia. Os dois pontos no final dizem ao curl para não solicitar senha:
export STRIPE_API_KEY=sk_test_... # your sandbox secret key
curl https://api.stripe.com/v1/payment_intents \
-u "$STRIPE_API_KEY:" \
-d amount=2000 \
-d currency=usd \
-d "automatic_payment_methods[enabled]=true"
A resposta é um PaymentIntent com um id começando com pi_, status: "requires_payment_method" e livemode: false. Esse último campo confirma que você usou uma chave de teste.
O Stripe também aceita -H "Authorization: Bearer $STRIPE_API_KEY", que é o formato usado pelo Apidog e pela maioria dos clientes HTTP. Ambos carregam a mesma chave; se você não tem certeza de qual estilo se encaixa na sua stack, nossa comparação de chaves de API e tokens bearer cobre os prós e contras. As requisições devem usar HTTPS; HTTP puro falha de imediato, conforme a referência de autenticação.
Em Python, o padrão atual do SDK é um StripeClient que lê a chave do ambiente:
import os
import stripe
client = stripe.StripeClient(os.environ["STRIPE_API_KEY"])
intent = client.v1.payment_intents.create({
"amount": 2000,
"currency": "usd",
"automatic_payment_methods": {"enabled": True},
})
print(intent.id, intent.livemode) # pi_..., False
Nenhuma string de chave aparece no arquivo. O mesmo código roda contra teste ou produção dependendo do que o ambiente fornecer.
Deixe seu agente de programação testar a chave do Stripe com o Apidog CLI
O curl prova que a chave funciona uma vez. Seu agente de programação pode transformar isso em uma verificação repetível por meio do Apidog CLI e manter a chave fora do projeto compartilhado. Configure uma vez (o token fica em Account Settings, API Access Token):
npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com # pick your agent when prompted
Depois, dê ao agente um único prompt:
Use Apidog CLI on project <id>. Create a "Stripe Test" environment with base URL
https://api.stripe.com. Add POST /v1/payment_intents with Bearer auth from
{{stripe_secret_key}} and a form-urlencoded body: amount=2000, currency=usd.
Create a test case asserting status 200, an id starting with pi_ and
livemode false, then run it and summarize any failures.
Os comandos que ele executa, verificados contra o Apidog CLI 2.2.7:
apidog environment create "Stripe Test" --project <id> --base-url https://api.stripe.com
apidog cli-schema get endpoint-create
apidog endpoint create --project <id> --file payment-intents.json
apidog cli-schema validate test-case-create --file pi-case.json
apidog test-case create --project <id> --file pi-case.json
apidog run --test-case <caseId> --project <id> -e <envId> \
--env-var "stripe_secret_key=$STRIPE_API_KEY" -r cli,json
O prompt especifica a codificação de formulário porque os endpoints v1 do Stripe não aceitam JSON. A asserção de livemode é seu fio de disparo: se alguém executar o caso com uma chave de produção, ele falha antes que uma segunda requisição saia. Na CI, a mesma linha apidog run lê a chave do armazenamento de segredos do seu pipeline; nosso guia de pipeline CI/CD com Apidog CLI tem uma versão pronta para copiar e colar. A definição da requisição é compartilhada; a credencial de produção nunca é.
Rotacionar chaves e o que fazer se uma vazar
O próprio guia de manuseio de chaves do Stripe é direto: presuma que qualquer coisa commitada em um repositório, colada em um chat ou impressa em um log está comprometida, mesmo que você não tenha certeza de que alguém a viu.
A rotação é integrada ao Dashboard. No menu de overflow de uma chave, escolha Rotate key, defina uma expiração para a chave antiga e copie a substituta. Ambas funcionam durante o período de carência, de até 7 dias, para que você possa fazer o rollout gradualmente e observar os logs de requisição em busca de retardatários. Now revoga a chave antiga imediatamente.
Se uma chave secreta ou restrita vazar:
- Rotacione-a imediatamente com uma expiração curta.
- Atualize todo servidor que a usava, confirme o tráfego nos logs de requisição e deixe a chave antiga expirar.
- Revise a atividade recente no Workbench em busca de qualquer coisa que sua integração não faria: contas conectadas não reconhecidas, repasses que você não iniciou, novas contas bancárias.
- Pause repasses suspeitos, reverta os que já foram enviados e reembolse cobranças fraudulentas rapidamente para evitar disputas.
- Rotacione suas outras chaves também. Se uma vazou, presuma que o canal que a vazou viu mais.
O Stripe faz varreduras em busca de chaves expostas e vai te notificar, às vezes desativando a chave proativamente, mas a detecção não é garantida. Pesquisar em seus repositórios e na configuração de CI por sk_live_ e rk_live_ é uma auditoria de cinco minutos, e um scanner de segredos em um hook de pre-commit impede que a próxima chegue lá. O Stripe nunca pede sua chave secreta, então qualquer mensagem que a solicite é phishing.
Erros comuns de chave de API do Stripe
| Sintoma | O que significa | Correção |
|---|---|---|
401 “No valid API key provided” |
Chave ausente, malformada ou revogada | Verifique o cabeçalho; confirme que a chave não foi rotacionada |
api_key_expired |
A chave foi rotacionada ou expirou | Pegue a chave atual no Dashboard |
secret_key_required |
Você enviou uma chave pk_ para um endpoint do lado do servidor |
Use sk_ ou rk_ no backend |
resource_missing em um id que você sabe que existe |
Modo errado: chave de teste contra um objeto de produção, ou o inverso | Combine o modo da chave com o do objeto |
403 “doesn’t have permissions to perform the request” |
A chave restrita não tem Read ou Write nesse recurso | Edite as permissões da chave; o corpo do erro indica o que falta |
livemode_mismatch |
Misturar chaves ou objetos de teste e de produção em uma única requisição | Mantenha cada ambiente inteiramente em um único modo |
Os casos de 401 e 403 correspondem a stripe.AuthenticationError e stripe.PermissionError no SDK de Python, conforme a referência de erros, então você pode capturá-los especificamente. Um caso menos óbvio: uma chave de produção que não criou transferências ou repasses por 180 dias fica limitada para essas ações, com uma opção Restore access na chave.
Perguntas frequentes
É seguro colocar uma chave publicável do Stripe no meu código de front-end?
Sim. Uma chave pk_ tokeniza dados de cartão, mas não consegue criar cobranças, ler clientes nem movimentar dinheiro. Apenas chaves secretas e restritas ficam no lado do servidor.
Posso usar uma chave restrita no modo de teste?
Sim. Chaves restritas existem nos dois modos (rk_test_ e rk_live_). O Stripe recomenda ajustar primeiro a versão de teste e depois criar uma chave de produção com permissões correspondentes.
O segredo de assinatura de webhook é o mesmo que minha chave de API?
Não. Os segredos de assinatura são emitidos por endpoint de webhook e servem apenas para verificar que um evento recebido veio do Stripe. Eles ficam em Webhooks, não na página de chaves de API. Se você está configurando isso, veja como testar webhooks do Stripe na CI.
O que acontece se eu usar uma chave de teste em produção?
As requisições são bem-sucedidas, mas nenhum cartão é cobrado e nenhum dinheiro se move. Como livemode retorna false em todo objeto, uma asserção sobre esse campo detecta o erro antes dos clientes.
A versão curta
Chaves publicáveis vão no cliente, chaves secretas e restritas ficam no servidor, teste e produção nunca se misturam, e restrita é melhor que secreta sempre que você puder delimitar o escopo. Mantenha a chave de produção em um cofre, passe a chave de teste para o Apidog CLI em tempo de execução e mantenha uma asserção de livemode em todo caso de teste que seu agente escrever.