> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mingopay.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Chaves de API

> Autentique chamadas, limite escopos e proteja credenciais.

Envie a chave no cabeçalho `Authorization`:

```http theme={"system"}
Authorization: Bearer mp_test_sua_chave
```

No painel, Nova chave inicia com Produção selecionado. Para testes, selecione Sandbox antes de criar a chave. A seleção do ambiente não altera as exigências de habilitação da conta nem as permissões da chave.

## Escopos

Passkeys e biometria podem ser cadastradas em Configurações > Segurança para entrar no painel e confirmar saques no lugar do aplicativo autenticador. O dispositivo pode solicitar biometria ou PIN. Essas confirmações pertencem às rotas privadas de sessão do painel; não substituem a chave Bearer e não adicionam permissões ao SDK/API comercial. KYC e demais controles do saque continuam obrigatórios. Outras ações que exigem TOTP mantêm essa exigência.

| Escopo | Permissão |
| - | - |
| `payment_intents:write` | Criar cobranças e confirmar cobranças no sandbox |
| `payment_intents:read` | Consultar, listar e sincronizar cobranças |
| `refunds:write` | Solicitar devoluções e simular devolução no sandbox |
| `balance:read` | Consultar saldo disponível |
| `subaccounts:read` | Listar e consultar subcontas, saldos, extratos e cobranças; sincronizar o vínculo |
| `subaccounts:write` | Criar, editar e desativar subcontas |

Use uma chave separada por serviço e ambiente. Conceda somente os escopos necessários, configure expiração e restrição de IP quando aplicável.

> [!WARNING]
>
> A chave é exibida integralmente somente na criação. Não registre o token completo em logs, analytics, mensagens de erro ou chamados de suporte.

## Respostas de autenticação

`401 invalid_api_key` indica token ausente, inválido, expirado, revogado ou bloqueado pela lista de IPs. `403 insufficient_scope` indica uma chave válida sem o escopo exigido pela rota.

Organizações suspensas (`restricted`) ou encerradas (`closed`) recebem `403 organization_not_active` em chamadas autenticadas por chave, tanto no sandbox quanto em produção. Uma chave válida não remove a suspensão; corrija a situação da conta antes de tentar novamente.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.