# 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 da Stripe às suas chaves de API. ‘’ Usar uma RAK limita o potencial de danos à sua empresa caso uma chave de API seja exposta a um agente mal-intencionado. Se uma chave de API restrita não tiver as permissões corretas para concluir uma solicitação de API, a Stripe retorna um [erro de solicitação inválida](https://docs.stripe.com/error-handling.md#invalid-request-errors).

## O que é uma chave de API restrita?

A restricted API key (RAK) is an API key your server-side applications include in Stripe API requests. A RAK starts with `rk_live_` or `rk_test_`. Unlike a secret key that can do anything in your Stripe account, a RAK can do only what you give it permission to do. When you create a RAK in the Stripe Dashboard, you select which Stripe resources the key can access and the permissions for each resource: **Read**, **Write**, or **None**. All Stripe APIs support restricted API keys.

Use RAKs as a defensive measure to protect your Stripe account in case your keys are exposed or compromised. If a bad actor obtains a RAK, they’re limited to that key’s permissions. For example, you could create a RAK that can only read dispute data and nothing else. If a bad actor obtained that key, they could only read dispute data. They couldn’t create charges, access customer payment methods, or trigger payouts.

A Stripe sempre recomenda usar RAKs em vez de chaves secretas não restritas, principalmente ao fornecer uma chave a um agente de IA. Use permissões RAK para limitar o que um agente pode fazer em sua conta.

Sempre siga as [práticas recomendadas](https://docs.stripe.com/keys-best-practices.md) ao usar RAKs para evitar exposição acidental ou comprometimento. Trate RAKs com a mesma cautela que trata as chaves secretas de API.

## 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                            |
| **Adequação para agentes de IA**   | Um agente pode fazer coisas que você não quer em sua conta                         | Você controla explicitamente as permissões do agente                                |
| **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                                     |
| **Conformidade**                   | Você pode controlar quem tem acesso às suas chaves, mas não o que elas podem fazer | Você pode controlar quem tem acesso às suas chaves e o que essas chaves podem fazer |
| **Recomendação da Stripe**         | Use com parcimônia e proteja com rigor                                             | **Preferencial**: use chaves restritas sempre que possível                          |

## Crie uma chave de API restrita

1. Na aba [ chaves API](https://dashboard.stripe.com/test/apikeys), siga de uma das seguintes formas:
   - Para criar uma nova chave restrita, clique em **Criar chave restrita**.
   - Para clonar uma chave existente, clique no menu overflow (⋯), depois selecione **Duplicar chave** para a chave que você deseja clonar. O valor padrão para cada permissão é o valor da chave clonada.
2. Se você estiver criando uma nova chave, pode escolher entre um conjunto pré-configurado de permissões ou começar sem nenhuma permissão.
3. Insira um nome no campo **Nome de chave**. Se você clonou uma chave existente, o nome padrão é o nome da chave clonada.
4. Para cada recurso que a nova chave deve acessar, selecione a permissão adequada: **Nenhuma**, **Leitura** ou **Gravação**. Se você usar o Connect, também pode selecionar a permissão para permitir que essa chave acesse contas conectadas. O valor padrão de todas as permissões é **Nenhuma**.
5. Clique em **Criar chave**.
6. Na caixa de diálogo, conclua a verificação de dois fatores que enviaremos.
7. Clique no valor-chave para copiá-lo.
8. Salve o valor da chave. Não é possível recuperá-lo mais tarde.
9. No campo **Adicionar uma nota**, insira a localização onde salvou a chave e clique em **Concluído**.

## Migrar de uma chave secreta para uma chave restrita

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

As seções a seguir descrevem 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 restrita.

### Criar uma chave de API restrita em uma área restrita

Crie uma chave de API restrita em uma [área restrita](https://docs.stripe.com/keys.md#test-live-modes) antes de criar uma chave no modo de produção.

1. Na [página de chaves de API](https://dashboard.stripe.com/apikeys) do Dashboard da Stripe, clique em **Criar chave restrita**.
2. Dê à nova chave um nome descritivo, como `billing-service-test`.
3. Não atribua nenhuma permissão à chave ainda. Você define as permissões após revisar o uso existente da chave secreta.

### Revise o uso da API da chave secreta

Use o uso atual da API pela chave secreta como base para definir as permissões de uma RAK.

- 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](https://docs.stripe.com/keys.md#view-request-logs) da chave secreta para ver as solicitações de API bem-sucedidas.

Use a tabela abaixo para mapear solicitações de API bem-sucedidas para as permissões que sua RAK precisa. Para cada recurso, defina a permissão como **Nenhuma**, **Leitura** ou **Gravação** com base no uso da API que você observou. As permissões de escrita implicam permissões de leitura: qualquer chave que possa gravar um recurso de API também pode lê-lo.

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

Por exemplo, se você observar chamadas bem-sucedidas para `GET /v1/customers` com sua chave secreta, precisará adicionar permissões de leitura para o recurso [Customer](https://docs.stripe.com/api/customers.md) às permissões da RAK substituta.

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

No seu ambiente de teste ou de homologação, substitua a chave secreta pela chave restrita no ambiente do servidor (por exemplo, em um [cofre de segredos](https://docs.stripe.com/keys-best-practices.md#use-a-secrets-vault) ou em uma variável de ambiente, caso a sua plataforma não ofereça um cofre de segredos). A biblioteca da Stripe e as chamadas feitas pelo servidor 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.
2. Selecione **Editar chave**.
3. 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.
2. Localize a chave restrita que você está configurando.
3. Clique no menu de mais opções (⋯) ao lado da chave.
4. 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 (⋯).
2. 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.