Credential permissions

​

Permission structure

{
  "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

​

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.