# Chaves de API restritas

Use chaves de API restritas para controlar o acesso da sua inscrição à API Stripe.

Você pode usar uma chave de API restrita (RAK) para atribuir permissões específicas da API Stripe às suas chaves de API. Usar uma RAK dessa forma limita o dano potencial para sua empresa caso uma chave de API seja exposta a um agente malicioso. Se uma chave de API restrita não tiver as permissões corretas para concluir uma solicitação de API, a Stripe retornará um [erro de solicitação inválida](https://docs.stripe.com/error-handling.md#invalid-request-errors).

## O que é uma chave de API restrita?

Quando você se registra na Stripe, recebe uma [chave secreta da API](https://docs.stripe.com/keys.md#obtain-api-keys) (começa com `sk_live_` ou `sk_test_`). Qualquer pessoa, agente ou sistema com sua chave secreta pode fazer *qualquer coisa* na sua conta Stripe: criar cobranças, emitir reembolsos, ler dados de clientes, acionar repasses e muito mais.

Uma chave de API restrita (RAK) começa com `rk_live_` ou `rk_test_` e só pode fazer o que você permitir. Quando você cria uma RAK no Dashboard da Stripe, seleciona quais recursos da Stripe a chave pode acessar e quais permissões ela terá para cada recurso: **Leitura**, **Gravação** ou **Nenhuma**. Todas as APIs da Stripe aceitam chaves de API restritas.

Você pode usar chaves restritas como medida de defesa para proteger sua conta Stripe caso suas chaves sejam expostas ou comprometidas. Se um agente malicioso obtiver uma chave de API restrita, ele ficará limitado às permissões atribuídas a essa chave. Por exemplo, você pode criar uma chave restrita que só possa ler dados de contestação e nada mais. Se um agente malicioso obtiver essa chave, ele só poderá ler dados de contestação. Ele não poderá criar cobranças, acessar formas de pagamento de clientes nem acionar repasses.

A Stripe recomenda que você sempre use chaves restritas em vez de chaves secretas irrestritas. Sempre siga as práticas recomendadas ao usar chaves restritas para evitar exposição ou comprometimento acidental. Consulte [Práticas recomendadas para gerenciar chaves secretas da API](https://docs.stripe.com/keys-best-practices.md).

## Por que usar chaves restritas em vez de chaves secretas?

|                                    | Chave secreta (`sk_`)                                      | Chave restrita (`rk_`)                                              |
| ---------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------- |
| **Escopo de acesso**               | Acesso total a todos os recursos da API                    | Apenas as permissões que você atribuir                              |
| **Impacto se for comprometida**    | Um agente malicioso pode fazer qualquer coisa na sua conta | Um agente malicioso só pode fazer o que a chave permitir            |
| **Compartilhamento com terceiros** | Perigoso: concede controle total ao terceiro               | Mais seguro: você concede apenas o acesso de que o terceiro precisa |
| **Princípio do menor privilégio**  | Não é possível alcançar isso com chaves irrestritas        | Você pode conceder permissões mínimas às chaves                     |
| **Recomendação da Stripe**         | Use com parcimônia e proteja com rigor                     | **Preferencial**: use chaves restritas sempre que possível          |

### Motivos para migrar para chaves de API restritas

- **Limite o impacto de um possível comprometimento da chave**: se uma chave restrita for comprometida, um agente malicioso só poderá acessar os recursos específicos que você permitiu.

- **Compartilhe chaves com terceiros com mais segurança**: a Stripe desaconselha o compartilhamento de chaves na maioria das situações, mas, em certas integrações de terceiros, talvez seja necessário compartilhar uma chave. Por exemplo, se um fornecedor precisar monitorar suas contestações, forneça a ele uma chave restrita com acesso somente leitura a contestações, e não sua chave secreta irrestrita. Se você estiver trabalhando com um terceiro, certifique-se de que ele siga as [práticas recomendadas](https://docs.stripe.com/keys-best-practices.md) para tratar a chave com segurança, como usar uma lista de permissões de IP, quando possível, para mitigar o risco de comprometimento da chave, e definir sua validade quando o relacionamento terminar.

- **Atenda às expectativas de conformidade**: muitas auditorias de segurança e estruturas de conformidade exigem o princípio do menor privilégio. As chaves restritas tornam isso simples.

- **Combine com restrições de IP**: você pode restringir qualquer chave restrita a um conjunto específico de endereços IP para adicionar uma camada extra de proteção.

## Migrar de uma chave secreta para uma chave restrita

As chaves de API restritas são substitutas diretas das chaves secretas da API. Para usar uma chave de API restrita, forneça-a ao seu código da mesma forma que fornece sua chave secreta, seguindo as [práticas recomendadas](https://docs.stripe.com/keys-best-practices.md) para evitar expor a chave acidentalmente. Todas as APIs da Stripe aceitam chaves de API restritas. Para obter os benefícios, você precisa configurar as permissões de cada chave restrita.

Veja uma abordagem passo a passo para migrar de uma chave secreta para uma chave restrita. Consulte [Atribuir permissões a uma chave de API restrita](https://docs.stripe.com/keys/restricted-api-keys.md#assign-permissions) para entender como reduzir as permissões de uma chave de API restrita.

### Revise o uso da API da chave secreta

Revise seu código e todas as integrações de terceiros para catalogar os produtos Stripe que você usa e as chamadas da API que atualmente faz com sua chave secreta.

Revise os [logs de solicitações no Workbench](https://dashboard.stripe.com/workbench/logs) da chave secreta. Você pode usar a tabela abaixo para mapear solicitações da API bem-sucedidas para as permissões de RAK necessárias.

| Método HTTP | Tipo de permissão da RAK |
| ----------- | ------------------------ |
| GET         | leitura                  |
| POST        | gravação                 |
| DELETE      | gravação                 |

Por exemplo, se você vir chamadas bem-sucedidas para `GET /v1/customers`, precisará adicionar permissões de leitura para o recurso [Cliente](https://docs.stripe.com/api/customers.md) às permissões da RAK que vai substituí-la.

### Crie uma chave restrita em uma área restrita

A Stripe recomenda criar uma chave restrita em uma área restrita da Stripe antes de criar uma chave de modo de produção.

1. Acesse a [página de chaves de API](https://dashboard.stripe.com/apikeys) no Dashboard da Stripe.
1. Clique em **Criar chave restrita**.
1. Dê a ela um nome descritivo, como `billing-service-test`.
1. Para cada recurso, defina a permissão como **Nenhuma**, **Leitura** ou **Gravação** com base no uso da API observado anteriormente.

### Configure seu ambiente de preparação para usar a chave restrita

Na sua inscrição de teste ou preparação, substitua a chave secreta pela chave restrita no ambiente do servidor (por exemplo, em uma variável de ambiente ou em um cofre de segredos). O SDK da Stripe e as chamadas HTTP que usam sua chave funcionam exatamente da mesma forma. A única diferença é o valor da chave.

### Revise os logs de solicitações da chave restrita em busca de erros e ajuste as permissões

Revise os logs da chave restrita em modo de teste na [lista de chaves](https://dashboard.stripe.com/apikeys), clicando no menu de mais opções (⋯) ao lado da chave e selecionando **Ver logs de solicitações**.

Se encontrar mensagens de erro como `403 ERR`, edite as permissões da chave restrita para adicionar as ações que falharam:

1. Clique no menu de mais opções (⋯) ao lado da chave.
1. Selecione **Editar chave**.
1. Repita seus testes em uma área restrita para confirmar que você atribuiu à chave restrita as permissões corretas.

Verifique os logs da sua inscrição em busca de erros da API Stripe. Se a chave restrita enviada com uma solicitação não tiver as permissões corretas, o corpo da resposta incluirá uma mensagem de erro explicando quais permissões adicionar.

### Crie uma chave restrita de modo de produção

Crie uma nova chave restrita em modo de produção com permissões equivalentes às da chave de modo de teste que você validou.

### Configure seu ambiente de produção para usar a chave restrita

Use a nova chave no seu ambiente de produção da mesma forma que configurou a chave de teste no ambiente de preparação.

### Aposente a chave secreta antiga

Quando tiver certeza de que tudo funciona no modo de teste, [altere](https://docs.stripe.com/keys.md#rolling-keys) ou [defina a validade](https://docs.stripe.com/keys.md#delete-secret-key) da sua antiga chave secreta no Dashboard. Isso garante que ninguém possa usá-la no futuro. Você pode definir uma validade postergada (de até 7 dias) se quiser uma margem de segurança durante a qual ainda possa reverter para a chave secreta.

## Atribuir permissões a uma chave de API restrita

Você pode configurar chaves restritas para atender aos seus casos de uso específicos, em linha com o princípio do menor privilégio: uma chave deve ter as permissões mínimas necessárias para fazer seu trabalho, e nada além disso. Aqui estão algumas abordagens práticas para atribuir permissões.

### Audite os logs de solicitações para determinar as permissões

1. Acesse a página [Chaves de API](https://dashboard.stripe.com/apikeys) no Dashboard.
1. Localize a chave restrita que você está configurando.
1. Clique no menu de mais opções (⋯) ao lado da chave.
1. Clique em **Ver logs de solicitações** para ver todas as solicitações feitas com essa chave.

Revise os endpoints da API que sua inscrição usou durante os testes com a chave restrita para ver exatamente quais recursos ela utilizou e se houve leitura ou gravação:

- Solicitações `GET` são leituras
- Solicitações `POST` e `DELETE` são gravações

Se sua inscrição funcionou corretamente nos testes, faça uma lista das chamadas bem-sucedidas nos logs de solicitações e compare essa lista com as permissões concedidas à chave restrita. Você pode remover quaisquer permissões que a chave não tenha usado. Para editar as permissões da chave:

1. Clique no menu de navegação (⋯).
1. Clique em **Editar chave**.

Se sua inscrição não estiver funcionando corretamente, você pode filtrar os logs de solicitações da chave para mostrar as solicitações malsucedidas e depois editar as permissões da chave no menu de chaves para adicionar as permissões correspondentes da API Stripe.

### Revise seu código

Você pode montar uma lista das permissões necessárias pesquisando chamadas do SDK da Stripe na sua base de código. Relacione cada chamada à permissão correspondente no Dashboard. Por exemplo:

- `PaymentIntent.create(...)` → **PaymentIntents: Gravação**
- `Customer.retrieve(...)` → **Customers: Leitura**
- `Dispute.list(...)` → **Disputes: Leitura**

Depois, configure as permissões da sua chave restrita para corresponder apenas ao que você encontrou.

### Comece com permissões amplas e remova o que não for necessário

Inicialmente, você pode conceder permissões amplas a uma chave restrita e, depois, remover permissões em excesso após revisar como ela é usada.

Em uma área restrita, crie uma chave restrita no menu de chaves de API. As permissões disponíveis são agrupadas por categorias. Se você souber que o uso da API Stripe não inclui uma categoria específica, como Stripe Billing, poderá selecionar **Nenhuma** para essa categoria. Caso contrário, selecione **Gravação** para as categorias relevantes ao uso da API Stripe. Permissões de **Gravação** incluem permissões de **Leitura**: se uma chave pode gravar em um recurso da API, ela também pode ler esse recurso.

Teste sua inscrição com a chave restrita de modo de teste, conforme descrito acima, para que a inscrição use a chave ao fazer solicitações à API Stripe. Teste todos os componentes da sua inscrição que usam APIs da Stripe.

## Use uma chave restrita por serviço ou caso de uso

Se você tiver vários serviços que usam APIs da Stripe (por exemplo, um serviço de faturamento, um serviço de relatórios e um manipulador de Webhook), crie uma chave restrita separada para cada serviço e conceda a cada chave apenas as permissões da API Stripe de que cada serviço precisa. Conceder permissões separadas permite limitar o impacto potencial de um comprometimento da chave caso qualquer um dos seus serviços seja comprometido.