Permissions - Afriex Business API

Every API key is scoped to a configurable set of permissions chosen when the key is created in the Dashboard. Requests are rejected with 401 Unauthorized when the key does not carry the permission the target endpoint requires, so pick the minimum set your integration needs.

Keys created before permissions existed carry no permissions and keep access to every endpoint, so no action is required for older keys. Provision a fresh key from the dashboard to opt into the scoped model.

How the check works

Header: requests carry the key in x-api-key (see Authentication).
Multiple permissions: where several are listed for one endpoint, any one of them is enough.
Failure mode: a key missing the required permission is rejected with 401 Unauthorized, exactly the same shape as an unrecognised, malformed, revoked, or disabled key. The API does not distinguish those cases on the wire.

Endpoint permission reference

Endpoint	Permission
`GET /customer`, `GET /customer/{customerId}`	`CUSTOMER.READ`
`POST /customer`	`CUSTOMER.CREATE`
`PATCH /customer/{customerId}`, `PATCH /customer/{customerId}/kyc`, `POST /customer/{customerId}/verify`	`CUSTOMER.UPDATE`
`DELETE /customer/{customerId}`	`CUSTOMER.DELETE`
`GET /payment-method`, `GET /payment-method/{paymentMethodId}`, `GET /payment-method/institution`, `GET /payment-method/institution/codes`, `GET /payment-method/resolve`, `GET /payment-method/virtual-account`, `GET /payment-method/pool-account`	`PAYMENT_METHOD.READ`
`POST /payment-method`, `DELETE /payment-method/{paymentMethodId}`, `POST /payment-method/virtual-account`, `GET /payment-method/crypto-wallet`, `POST /payment-method/virtual-account/simulate-transfer` (sandbox only)	`PAYMENT_METHOD.CREATE`
`POST /transaction`	`TRANSACTION.DEPOSIT.CREATE`, `TRANSACTION.WITHDRAW.CREATE` or `TRANSACTION.SWAP.CREATE`
`POST /transaction/{transactionId}/authorize`, `POST /transaction/pool-account`	`TRANSACTION.DEPOSIT.CREATE`
`POST /transaction/{transactionId}/simulate` (sandbox only)	`TRANSACTION.DEPOSIT.CREATE` or `TRANSACTION.WITHDRAW.CREATE`
`GET /transaction`, `GET /transaction/{transactionId}`, `GET /transaction/{transactionId}/advice`	`TRANSACTION.HISTORY.READ`
`GET /org/balance`, `GET /org/rates`	`WALLET.BALANCES.READ`
`POST /media/url`	`PAYMENT_METHOD.CREATE`
`POST /sme-registration`	`COMPLIANCE.KYB.SUBMIT`
`GET /sme-registration/status`	`COMPLIANCE.KYB.READ`
`POST /checkout-session`	`CHECKOUT_LINK.CREATE`
`GET /payment-batch`, `GET /payment-batch/{batchId}`, `GET /payment-batch/{batchId}/recipients`	`PAYMENT_METHOD.READ`
`POST /payment-batch`, `PATCH /payment-batch/{batchId}`, `DELETE /payment-batch/{batchId}`, `POST /payment-batch/{batchId}/recipients`, `POST /payment-batch/{batchId}/recipients/bulk`, `PATCH /payment-batch/{batchId}/recipients/{recipientId}`, `DELETE /payment-batch/{batchId}/recipients/{recipientId}`	`PAYMENT_METHOD.CREATE`
`POST /payment-batch/{batchId}/withdraw`	`TRANSACTION.WITHDRAW.CREATE`
`GET /payment-batch/{batchId}/sessions`	`TRANSACTION.HISTORY.READ`
`POST /org/balance/topup`, `POST /webhooks/trigger`	None; any valid key

Managing keys? Head to Developer → API keys in the Dashboard to create, rotate, or revoke them.