> ## 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.

# Credential permissions

> Fine-grained access control per module in the Payments API

Payment API credentials use a fixed permission schema to restrict what each integration can do.

## Permission structure

```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
  }
}
```

## Modules and effects

| Module           | Field                     | Main effect                                                          |
| ---------------- | ------------------------- | -------------------------------------------------------------------- |
| Balance          | `balance.read`            | Allows `GET /v1/balance`                                             |
| Transactions     | `transactions.read`       | Allows list and get transaction                                      |
| Transactions     | `transactions.write`      | Allows create and simulate transaction                               |
| Customers        | `customers.read`          | Allows list and get customer                                         |
| Customers        | `customers.write`         | Allows create customer                                               |
| Customers        | `customers.edit`          | Allows update customer                                               |
| Cashouts         | `cashouts.read`           | Allows list and get cashout                                          |
| Cashouts         | `cashouts.write`          | Allows create, cancel, and simulate cashout                          |
| Cashouts         | `cashouts.allowAnyPixKey` | Allows arbitrary PIX key in cashout create                           |
| Cashout accounts | `cashoutAccounts.write`   | Allows creating and activating a PIX cashout account through the API |
| Disputes         | `disputes.read`           | Allows listing and retrieving dispute details                        |
| Disputes         | `disputes.write`          | Allows submitting or updating a response and attaching evidence      |

## Important cashout rules

1. Always use `withdrawNowAvailable` from `GET /v1/balance` to set cashout amount.
2. If `requiresFullWithdrawalNow = true`, amount must be exactly `withdrawNowAvailable`.
3. When `cashouts.allowAnyPixKey = false`, arbitrary PIX key destination is not allowed.
4. For crypto cashouts, `cryptoPayoutAccountId` must reference an active, verified wallet belonging to the merchant; wallet addresses cannot be sent directly through the API.
5. Operation environment (`Sandbox` or `Production`) is determined by the authenticated credential.
6. `cashoutAccounts.write` also requires the feature to be enabled for the merchant by a Safefy administrator.

## Best practices

1. Use separate credentials per internal service.
2. Apply least privilege for each credential.
3. Avoid using a single full-access credential for every integration.
4. Revoke and rotate credentials immediately if exposure is suspected.