# Como obter as credenciais da API

As credenciais são um par `client_id` + `client_secret` criado no painel da ValidaPay. Com elas você
troca por um `access_token` em `POST /auth/token` e passa a chamar a API.

Crie em: `https://app.validapay.com.br/integracao/api`

## Passo a passo

### 1. Abra Integração → API

No painel, vá em **Integração → API**. A tela tem duas abas: **Criar Credencial** e **Credenciais Ativas**.

### 2. Confira o ambiente

Credenciais são **por ambiente**: uma criada no sandbox não funciona em produção e vice-versa. Verifique
o seletor de ambiente do painel antes de criar: o par gerado pertence ao ambiente que estiver ativo.

| Ambiente | Base URL |
|---|---|
| Sandbox | `https://sandbox.validapay.com.br` |
| Produção | `https://api.validapay.com.br` |

### 3. Dê um nome à credencial

Na aba **Criar Credencial**, preencha o campo **Nome**. Ele é obrigatório e serve só para você
identificar depois na lista. Use algo como `backend-producao` ou `integracao-erp`.

### 4. Selecione as permissões (scopes)

Clique em **Selecionar permissões** e marque os escopos no modal. **Pelo menos um é obrigatório**: sem
escopo o botão de criar fica desabilitado.

Peça só o que a integração usa. O `access_token` carrega exatamente os escopos da credencial, e uma rota
chamada sem o escopo correspondente responde `403`.

### 5. Crie e copie o par

Clique em **Criar Credencial**. O painel mostra o cartão de confirmação com **Client ID** e
**Client Secret**.

Guarde o `client_secret` em um gerenciador de senhas ou variável de ambiente. Ele continua visível na
aba **Credenciais Ativas**, mas não deve aparecer em tela compartilhada, log ou repositório.

### 6. Troque por um access_token

```http
POST /auth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=SEU_CLIENT_ID
&client_secret=SEU_CLIENT_SECRET
&scope=pix.cob/write
```

O `scope` da requisição precisa estar contido nos escopos da credencial. Veja [Autenticação](/referencia/post-autenticacao.md)
para o formato da resposta e a validade do token.

## Escopos disponíveis

| Grupo | Escopo | O que libera |
|---|---|---|
| Cobranças (PIX) | `pix.cob/read` | Consultar cobranças |
| Cobranças (PIX) | `pix.cob/write` | Criar cobranças |
| Cobranças Avulsas | `payment.methods/write` | Tokenizar cartão |
| Contas | `accounts/read` | Consultar dados da conta |
| Contas | `accounts/write` | Operações de escrita na conta |
| Propostas | `proposals/read` | Consultar formulários e propostas |
| Propostas | `proposals/write` | Criar/atualizar formulários |
| Carteira | `wallet/read` | Saldo e extrato |
| Carteira | `wallet/write` | Transferências |
| Webhooks | `webhooks/read` | Listar webhooks |
| Webhooks | `webhooks/write` | Criar, atualizar e deletar webhooks |
| Subcontas | `subaccounts/read` | Consultar subcontas |
| Subcontas | `subaccounts/write` | Criar/atualizar subcontas |
| Produtos | `products/read` | Consultar produtos |
| Produtos | `products/write` | Criar/atualizar produtos |
| Checkout | `checkouts/read` | Consultar checkouts |
| Checkout | `checkouts/write` | Criar/atualizar links de checkout |
| Clientes | `customers/read` | Consultar clientes |
| Clientes | `customers/write` | Criar/atualizar clientes |
| Clientes | `customers/delete` | Excluir clientes |
| Assinaturas | `subscriptions/read` | Consultar assinaturas |
| Assinaturas | `subscriptions/write` | Gerenciar assinaturas |
| Notas Fiscais | `nota.fiscal/read` | Consultar notas fiscais |
| Notas Fiscais | `nota.fiscal/write` | Emitir e cancelar notas fiscais |

## Gerenciando credenciais

A aba **Credenciais Ativas** lista os pares já criados. Ali você consulta o `client_id`, revê o
`client_secret` e remove credenciais.

A remoção é definitiva: qualquer integração que use aquele par para de obter token na hora. Se precisar
rotacionar, crie a nova credencial, aponte a aplicação para ela e só então remova a antiga.