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

# Permissões da credencial

> Controle fino de acesso por módulo na API de pagamentos

As credenciais da API de pagamentos usam um schema fixo de permissões para limitar o que cada integração pode fazer.

## Estrutura da permissão

```json theme={null}
{
  "version": 1,
  "balance": {
    "read": true
  },
  "transactions": {
    "read": true,
    "write": true
  },
  "customers": {
    "read": true,
    "write": true,
    "edit": true
  },
  "cashouts": {
    "read": true,
    "write": true,
    "allowAnyPixKey": false
  },
  "cashoutAccounts": {
    "write": false
  },
  "disputes": {
    "read": false,
    "write": false
  }
}
```

## Módulos e efeitos

| Módulo          | Campo                     | Efeito principal                                           |
| --------------- | ------------------------- | ---------------------------------------------------------- |
| Saldo           | `balance.read`            | Permite `GET /v1/balance`                                  |
| Transações      | `transactions.read`       | Permite listagem e detalhe de transações                   |
| Transações      | `transactions.write`      | Permite criação e simulação de transações                  |
| Clientes        | `customers.read`          | Permite listagem e detalhe de clientes                     |
| Clientes        | `customers.write`         | Permite criação de clientes                                |
| Clientes        | `customers.edit`          | Permite atualização de clientes                            |
| Saques          | `cashouts.read`           | Permite listagem e detalhe de saques                       |
| Saques          | `cashouts.write`          | Permite criar, cancelar e simular saques                   |
| Saques          | `cashouts.allowAnyPixKey` | Permite enviar chave PIX arbitrária no create cashout      |
| Contas de saque | `cashoutAccounts.write`   | Permite cadastrar e ativar conta PIX de saque pela API     |
| Disputas        | `disputes.read`           | Permite listar e consultar detalhes de disputas            |
| Disputas        | `disputes.write`          | Permite enviar ou atualizar a resposta e anexar evidências |

## Regras importantes de saque

1. Sempre use `withdrawNowAvailable` de `GET /v1/balance` para definir o valor de saque.
2. Se `requiresFullWithdrawalNow = true`, o valor deve ser exatamente `withdrawNowAvailable`.
3. Quando `cashouts.allowAnyPixKey = false`, a integração não pode sacar para chave PIX arbitrária.
4. Para saques cripto, `cryptoPayoutAccountId` deve referenciar uma carteira ativa e verificada do próprio merchant; o endereço não pode ser enviado diretamente pela API.
5. O ambiente da operação (`Sandbox` ou `Production`) é definido pela própria credencial autenticada.
6. `cashoutAccounts.write` também exige que a funcionalidade esteja habilitada para a organização pelo administrador Safefy.

## Boas práticas

1. Crie credenciais separadas por serviço interno.
2. Aplique menor privilégio possível em cada credencial.
3. Não use uma única credencial com todos os módulos habilitados para todos os sistemas.
4. Revogue e gere nova credencial imediatamente em caso de suspeita de vazamento.