# Chaves de API Use chaves de API para autenticar solicitações de API. A Stripe autentica solicitações de API usando as chaves de API da sua conta. Se uma solicitação não incluir uma chave válida, a Stripe retorna um [erro de solicitação inválida](https://docs.stripe.com/error-handling.md#invalid-request-errors). Se uma solicitação incluir uma chave excluída ou expirada, a Stripe retorna um [erro de autenticação](https://docs.stripe.com/error-handling.md#authentication-errors). Use o [Dashboard de Desenvolvedores](https://dashboard.stripe.com/test/apikeys) para criar, revelar, excluir e alternar chaves de API. Você pode acessar suas chaves de API na aba [Chaves de API](https://dashboard.stripe.com/test/apikeys). > #### Se você é novo na Stripe > > - **Mantenha sua empresa segura:** leia nossas [práticas recomendadas](https://docs.stripe.com/keys-best-practices.md) para gerenciamento de chaves. - **Desenvolva e teste**: use suas *chaves de área restrita (modo de teste)*. As chaves de área restrita começam com `pk_test_` (publicável), `rk_test_` (restrita) e `sk_test_` (secreta). Elas permitem que você faça testes sem afetar os dados na área de produção. - **Quando estiver pronto para aceitar pagamentos reais**: mude para suas **chaves de modo de produção**, que começam com `pk_live_`, `rk_live_` e `sk_live_`. Consulte [Mudar para o modo de produção](https://docs.stripe.com/keys.md#switch-to-live-mode) para ver as instruções. - **Se precisa encontrar um segredo de assinatura de webhook**: os segredos de webhook são separados das chaves de API. Encontre-os na seção [Webhooks](https://dashboard.stripe.com/webhooks) do Dashboard, em cada endpoint de webhook. ## Tipos de chave Quando você se registra para uma conta Stripe, criamos três tipos de chaves de API para você: | Tipo​​ | Seguro para expor | Descrição | | --------------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Chave de API restrita (RAK)`rk_...` | Não | Chave de API com permissões que você controla. Limite os danos à sua empresa que um agente mal-intencionado poderia causar caso obtivesse sua chave. Crie quantas RAKs quiser e atribua-as a diferentes partes do seu aplicativo. [Este guia](https://docs.stripe.com/keys/restricted-api-keys.md) explica como configurar e usar RAKs. | | Chave de API publicável | Sim | Chave de API que pode ser inserida em código de front-end ou em aplicativos que você distribui. | | Chave de API secreta`sk_...` | Não | Chave de API com permissões irrestritas em todas as APIs da Stripe. Como não é possível limitar as permissões, não recomendamos o uso de chaves secretas para novos casos de uso e, para integrações existentes, recomendamos migrar o uso de chaves secretas para RAKs. | | Chave de API da organização`sk_org_...` | Não | Chave de API que funciona no nível da organização. Assim como as chaves secretas ou restritas no nível da conta, opera no nível da [organização](https://docs.stripe.com/get-started/account/orgs.md) para gerenciar várias contas Stripe de uma só vez. [Este guia](https://docs.stripe.com/keys/organization-api-keys.md) explica como configurar e usar chaves de API da organização. | Também aceitamos [chaves de API gerenciadas](https://docs.stripe.com/keys/managed-api-keys.md) emitidas por determinadas plataformas de hospedagem. Chaves gerenciadas são chaves de API secretas que uma plataforma de hospedagem entrega diretamente para seus aplicativos hospedados. Não é necessário lidar com chaves gerenciadas diretamente; seu provedor de hospedagem as emite e as rotaciona para você. > #### Segredos da assinatura Webhook > > Os segredos de assinatura de webhook não são chaves de API, são segredos específicos de cada webhook que seu receptor de webhook usa para se certificar de que os webhooks realmente vieram da Stripe. Você pode encontrar o segredo de assinatura de cada endpoint de webhook na seção [Webhooks](https://dashboard.stripe.com/webhooks) do Dashboard. Se você criou sua conta Stripe antes de maio de 2026, pode ser que não tenha nenhuma chave de API restrita. Recomendamos criar RAKs e migrar das chaves secretas. Você é responsável por gerenciar suas chaves de API com segurança. Leia nosso guia de [práticas recomendadas para proteger chaves de API](https://docs.stripe.com/keys-best-practices.md). ### Área restrita e modo de produção Todas as solicitações da API da Stripe ocorrem em uma ‘*‘área restrita’* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes)’ ou no ‘*‘modo de produção’* (Use this mode when you’re ready to launch your app. Card networks or payment providers process payments)’. Você pode usar uma área restrita para testar sua integração e acessar dados de teste, e o modo de produção para acessar dados reais da conta. Cada modo tem seu próprio conjunto de chaves de API, e os objetos de um modo não são acessíveis no outro. Por exemplo, um [objeto de produto](https://docs.stripe.com/api/products/object.md) de área restrita não pode fazer parte de um pagamento em modo de produção. | Tipo | Quando usar | Objetos | Como usar | Considerações | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Áreas restritas | Use uma área restrita e as chaves de API de teste associadas enquanto cria sua integração. Em uma área restrita, as bandeiras de cartão e os provedores de pagamento não processam pagamentos. | As chamadas de API retornam objetos simulados. Por exemplo, você pode recuperar e usar os objetos de teste `account`, `payment`, `customer`, `charge`, `refund`, `transfer`, `balance` e `subscription`. | Use [cartões de crédito e contas de teste](https://docs.stripe.com/testing.md#cards). Não é possível aceitar formas de pagamento reais ou trabalhar com contas reais. | O [Identity](https://docs.stripe.com/identity.md) não realiza nenhuma verificação. Além disso, os [objetos de conta](https://docs.stripe.com/api/accounts/object.md) do Connect não retornam campos confidenciais. | | Modo de produção | Use o modo de produção e as chaves de API de produção quando estiver pronto para lançar sua integração e aceitar dinheiro de verdade. No modo de produção, as bandeiras de cartão e os provedores de pagamento processam pagamentos. | As chamadas de API retornam objetos reais. Por exemplo, você pode recuperar e usar objetos reais `account`, `payment`, `customer`, `charge`, `refund`, `transfer`, `balance` e `subscription`. | Aceite cartões de crédito reais e trabalhe com contas de clientes. É possível aceitar autorizações de pagamento, cobranças e capturas de cartões de crédito e contas. | Contestações têm um fluxo mais detalhado e um [processo de testes](https://docs.stripe.com/testing.md#disputes) mais simples. Além disso, algumas [formas de pagamento](https://docs.stripe.com/payments/payment-methods.md) têm um fluxo mais detalhado e exigem mais etapas. | ## Proteja suas chaves Apenas chaves publicáveis são seguras para expor fora do backend da sua aplicação. Você é responsável por proteger as demais chaves de API da Stripe, incluindo chaves de API restritas. Veja algumas formas de proteger suas chaves: - Armazene chaves sensíveis em um cofre de segredos fornecido pela sua plataforma de hospedagem. [Este post do blog](https://stripe.dev/blog/securing-stripe-api-keys-aws-automatic-rotation) oferece um exemplo. Se você não puder usar um cofre de segredos, use variáveis de ambiente para fornecer as chaves aos seus aplicativos de backend. - Não insira chaves no código-fonte nem em arquivos de configuração incluídos em controle de versão. - [Limite as chaves a endereços IP específicos](https://docs.stripe.com/keys.md#limit-api-secret-keys-ip-address) para que apenas seus servidores possam usá-las. - [Faça a rotação de chaves](https://docs.stripe.com/keys.md#rolling-keys) quando membros da equipe com acesso às chaves saírem da sua organização. - Não compartilhe chaves por e-mail, conversar ou outros canais não criptografados. Para um guia abrangente, consulte [práticas recomendadas para gerenciar chaves de API secretas](https://docs.stripe.com/keys-best-practices.md). Também mantemos [uma biblioteca de habilidades](https://github.com/stripe/ai/tree/main/skills) para ajudar agentes de IA a seguir essas práticas recomendadas. ## Gerencie suas chaves de API Use o [Dashboard](https://dashboard.stripe.com/apikeys) para criar, revelar, modificar, excluir e alternar suas chaves de API. #### Crie uma chave de API restrita Use [chaves de API restritas](https://docs.stripe.com/keys/restricted-api-keys.md) (RAKs) para a maioria dos casos de uso. Com uma RAK, você pode atribuir exatamente as permissões que sua integração precisa, reduzindo o dano que um agente malicioso poderia causar à sua empresa caso obtivesse sua chave. - Siga as instruções em [Chaves de API restritas](https://docs.stripe.com/keys/restricted-api-keys.md) para criar uma RAK, configurar suas permissões e migrar a partir de chaves secretas. #### Crie uma chave de API secreta Crie uma chave de API secreta sem restrições somente quando sua integração exigir acesso a todas as APIs e recursos da Stripe sem restrição. Se um agente malicioso obtiver sua chave secreta, ele poderá prejudicar sua empresa. Recomendamos usar RAKs. 1. Na aba [chaves API](https://dashboard.stripe.com/test/apikeys), clique em **Criar chave secreta**. 1. Na caixa de diálogo, insira o código de verificação que enviamos por e-mail ou mensagem de texto. Se a caixa de diálogo não continuar automaticamente, clique em **Continuar**. 1. Insira um nome no campo **Nome da chave** e clique em **Criar**. 1. Clique no valor-chave para copiá-lo. 1. Salve o valor da chave. Não é possível recuperá-lo mais tarde. 1. No campo **Adicionar uma nota**, insira a localização onde salvou a chave e clique em **Concluído**. ### Revelar uma chave API Ao criar uma chave secreta em modo de produção, ela é exibida uma vez antes de você salvá-la. Copie a chave antes de salvar, pois não será possível revelá-la depois. No modo de produção, você pode revelar apenas as chaves de API que criamos para você, como uma chave secreta padrão ou uma chave gerada por uma rotação programada. No modo de área restrita, você pode sempre ver todas as suas chaves de API, incluindo as restritas e as secretas. > Armazene chaves sensíveis em um lugar onde você não as perderá, como um cofre de segredos fornecido pela sua plataforma. Não coloque chaves no código da sua aplicação. As chaves de API publicáveis não são sensíveis, por isso as exibimos por padrão e você não precisa fazer nada para revelá-las. Não conseguimos recuperar chaves que você esqueceu ou às quais perdeu o acesso. Se você perder uma chave, alterne-a ou exclua-a e crie outra. #### Para revelar uma RAK em modo de produção Você pode revelar apenas as RAKs em modo de produção que criamos para você. Se você criar uma RAK por conta própria, não poderá revelá-la depois de tê-la visto uma vez. 1. Na aba [Chaves de API](https://dashboard.stripe.com/apikeys) no modo de produção, na lista **Chaves restritas**, clique em **Revelar chave de produção** para a chave que você deseja revelar. 1. Clique no valor-chave para copiá-lo. 1. Guarde o valor da chave no [cofre de segredos](https://docs.stripe.com/keys-best-practices.md#use-a-secrets-vault) da sua plataforma. Se a sua plataforma não oferecer um cofre, utilize uma variável de ambiente. 1. Clique em **Ocultar chave de produção**. #### Para revelar uma chave de API secreta em modo de produção Você pode revelar apenas as chaves secretas em modo de produção que criamos para você. Se você criar uma chave secreta por conta própria, não poderá revelá-la depois de tê-la visto uma vez. 1. Na aba [Chaves de API](https://dashboard.stripe.com/apikeys) no modo de produção, na lista **Chaves padrão**, clique em **Revelar chave de produção** para a chave que você deseja revelar. 1. Clique no valor-chave para copiá-lo. 1. Guarde o valor da chave no [cofre de segredos](https://docs.stripe.com/keys-best-practices.md#use-a-secrets-vault) da sua plataforma. Se a sua plataforma não oferecer um cofre, utilize uma variável de ambiente. 1. Clique em **Ocultar chave de produção**. 1. Clique no menu de overflow (⋯), depois selecione **Editar chave** para a chave à qual você quer adicionar uma nota. 1. No campo **Notas**, insira o local onde você salvou a chave e clique em **Salvar**. ### Limite uma chave API a certos endereços IP Você pode limitar uma chave de API secreta ou restrita a um intervalo de endereços IP ou a um ou mais endereços IP específicos. A Stripe recomenda habilitar restrições de IP em todas as chaves no modo de produção para evitar o uso a partir de locais não autorizados. Use listas de permissões de IP separadas para chaves separadas quando aplicável (por exemplo, para distinguir entre ambientes de staging e de produção). Endereços IP devem usar o protocolo IPv4, e você pode especificar qualquer faixa CIDR válida. Por exemplo, você pode especificar o alcance `100.10.38.0 - 100.10.38.255` como`100.10.38.0/24`. Todos os endereços IP nesse alcance devem começar por `100.10.38`. 1. Na aba [Chaves de API](https://dashboard.stripe.com/test/apikeys), na lista **Chaves restritas** ou **Chaves padrão**, clique no menu de opções (‘⋯’) da chave que você deseja revelar. 1. Selecione **Gerenciar restrições de IP** > **Limitar o uso a um conjunto de endereços IP**. 1. Siga de uma das seguintes formas: - Insira um ou mais endereços IP individuais no campo **IP address**. - Para um intervalo de endereços IP, insira o primeiro endereço do intervalo (usando a notação Classless Inter-Domain Routing (CIDR)) no campo **Endereço IP**. Insira o tamanho do prefixo de rede no campo **CIDR**. 1. Para adicionar outro endereço IP ou intervalo, clique em **Adicionar mais**. 1. Clique em **Salvar**. ### Alterar o nome ou nota de uma chave API 1. Na aba [ chaves API](https://dashboard.stripe.com/test/apikeys), clique no menu (⋯) para a chave que você quer mudar. 1. Selecione a **Editar chave**. 1. Faça o seguinte: - Para mudar o nome, insira um novo nome no campo **Nome da chave**. - Para alterar o texto da nota, insira o novo texto no campo **Nota**. 1. Clique em **Salvar**. ### Expirar uma chave de API Se você expirar uma chave de API secreta ou uma chave de API restrita, você precisa criar uma nova e atualizar qualquer código que use a chave expirada. Qualquer código que use a chave expirada não pode mais fazer chamada da API. > Você não pode expirar uma chave publicável. 1. Na aba [Chaves de API](https://dashboard.stripe.com/test/apikeys), na lista **Chaves restritas** ou **Chaves padrão**, clique no menu de opções (‘⋯’) da chave que você deseja expirar. 1. Selecione **Expirar chave**. 1. No diálogo, clique em **Expirar chave**. Se você não quiser mais expirar a chave, clique em **Cancelar**. ### Girar uma chave de API Girar uma chave API revoga e gera uma chave de substituição pronta para uso imediatamente. Você também pode programar uma chave API para girar após um certo tempo. A chave de substituição é nomeada da seguinte forma: - O nome de chave publicável de substituição é sempre `Chave publicável`. - O nome da chave secreta de substituição é sempre `Chave secreta`. - O nome da chave restrita de substituição é o mesmo da chave rotacionada. Renomear uma chave API secreta ou restrita editando-a. Gire uma chave API em cenários como: - Se você perder uma chave API secreta ou restrita no modo ativo e não conseguir recuperá-la no Dashboard. - Se uma chave API secreta ou restrita for comprometida e você precisar revogá-la para bloquear quaisquer solicitações API potencialmente maliciosas que possam usar a chave. - Se um membro da equipe com acesso à chave sair da sua organização ou mudar de função. - Se a sua política exigir a rotação de chaves em determinados intervalos. #### Para girar uma chave API 1. Na aba de [chaves API](https://dashboard.stripe.com/test/apikeys), clique no menu de overflow (⋯) para girar a chave que você escolheu. 1. Selecione **Girar chave**. 1. Selecione uma data de validade no menu suspenso **Expiração**. Se você escolher **Agora**, a chave antiga é excluída. Se você especificar um tempo, o tempo restante até a chave expirar aparece abaixo do nome da chave. 1. Clique em **Girar chave de API**. 1. Clique no valor-chave para copiá-lo. 1. Salve o valor da chave. Não é possível recuperá-lo mais tarde. 1. No campo **Adicionar uma nota**, insira a localização onde salvou a chave e clique em **Salvar** ou **Pronto**. ### Restaurar o acesso de uma chave de API Uma chave de API pode ter seu acesso limitado se não for usada para criar transferências, repasses ou atualizações de destinos de repasse por mais de 180 dias. Você não pode usar uma chave de acesso limitado para criar repasses, transferências ou destinos de repasse. Você pode restaurar o acesso para usar a chave normalmente ou para realizar uma ação bloqueada. #### Para restaurar o acesso de uma chave de API 1. Na aba [Chaves API](https://dashboard.stripe.com/test/apikeys), clique no menu de mais opções (⋯) da chave que você deseja restaurar. 1. Selecione **Restaurar acesso**. 1. Clique em **Restaurar**. ## Visualize logs de solicitações de API de uma chave Para abrir os logs de [solicitações de API ](https://docs.stripe.com/development/dashboard/request-logs.md), clique no menu de overflow (⋯) para qualquer tecla, depois selecione **Ver logs de solicitação**. Abrir logs redireciona você para o Stripe Dashboard. ## Mudar para modo de produção Quando estiver pronto para aceitar pagamentos reais, use chaves de API de modo ativo em vez de chaves de sandbox (teste). Na página [Chaves de API](https://dashboard.stripe.com/apikeys), alterne de **modo de área restrita** para **modo de produção**. A página agora mostra suas chaves de API do modo de produção. > #### Conclua checklist de lançamento > > Mudar chaves de API é só uma etapa. Revise o [checklist de lançamento](https://docs.stripe.com/get-started/checklist/go-live.md) completo para garantir que sua integração esteja pronta para produção. ### Chaves publicáveis (do lado do cliente) Copie sua **chave publicável em modo de produção** (começa com `pk_live_`) e substitua a chave `pk_test_` no seu código do lado do cliente. É seguro incorporar essa chave no seu código ou aplicativos. ### Chaves de API restritas ou secretas (do lado do servidor) As chaves de API do lado do servidor são sensíveis, por isso revise nossas [práticas recomendadas para gerenciar chaves de API secretas](https://docs.stripe.com/keys-best-practices.md). Recomendamos gerar [chaves de API restritas](https://docs.stripe.com/keys/restricted-api-keys.md) para o seu código do lado do servidor, a fim de limitar o dano à sua empresa caso suas chaves sejam expostas ou comprometidas. 1. Antes de começar a usar uma chave de modo de produção no aplicativo backend, remova qualquer chave de API escrita diretamente no código. Em vez disso, use um [cofre de segredos](https://docs.stripe.com/keys-best-practices.md#use-a-secrets-vault) para fornecer a chave da área restrita e confirme que o aplicativo continua funcionando. Se a sua plataforma não oferecer um cofre de segredos, você pode usar uma variável de ambiente. 1. [Revele](https://docs.stripe.com/keys.md#reveal-an-api-key) e copie suas **chaves em modo de produção** (que começam com `rk_live_` ou `sk_live_`) e armazene-as com segurança no seu ambiente de servidor. 1. Configure o ambiente do servidor para fornecer chaves do modo de produção em vez de chaves da área restrita à sua aplicação. #### Chaves de assinatura de Webhook (lado do servidor) Se você usar Webhooks, atualize o URL de cada endpoint de Webhook e copie o novo **segredo de assinatura** na seção [Webhooks](https://dashboard.stripe.com/webhooks) do Dashboard. ## See also - [Práticas recomendadas para gerenciar chaves de API secretas](https://docs.stripe.com/keys-best-practices.md) - [Proteção contra chaves de API comprometidas](https://support.stripe.com/questions/protecting-against-compromised-api-keys) - [Por que minha chave de API tem acesso limitado?](https://support.stripe.com/questions/why-does-my-api-key-have-limited-access)