Permissions & bundles

An institution API key holds one or more bundles, chosen when the key is created. Each bundle grants a set of permissions, and each endpoint needs one permission. A key can call an endpoint if any of its bundles grants that permission. A key with no matching bundle gets 401 with code -93.

Bundles

Bundle	What it allows	Permissions
PAYMENTS_READ	Payments — read collections, disbursements and payments balances, including reads added later	COLLECTIONS_READ, DISBURSEMENTS_READ, PAYMENTS_BALANCES_READ
COLLECTIONS_WRITE	Collections — create, update and delete deposit references, and read collections	COLLECTIONS_CREATE, COLLECTIONS_READ, COLLECTIONS_UPDATE, COLLECTIONS_DELETE, PAYMENTS_BALANCES_READ
DISBURSEMENTS_WRITE	Disbursements — manage beneficiaries and batches, and create batches, which execute immediately	DISBURSEMENTS_CREATE, DISBURSEMENTS_READ, DISBURSEMENTS_UPDATE, DISBURSEMENTS_DELETE, DISBURSEMENTS_APPROVE, PAYMENTS_BALANCES_READ
TRADING_READ	Trading — read orders, balances and history	TRADING_READ, ACCOUNT_BALANCES_READ, TRANSACTION_HISTORY_READ
TRADING_WRITE	Trading — place, modify and cancel orders, convert, and read orders, balances and history	TRADING_READ, TRADING_CREATE, CONVERT_CREATE, ACCOUNT_BALANCES_READ, TRANSACTION_HISTORY_READ
TREASURY_READ	Treasury — read balances, history, deposit details, sub-accounts, withdrawals and VALR Pay payments	ACCOUNT_BALANCES_READ, TRANSACTION_HISTORY_READ, DEPOSITS_READ, SUB_ACCOUNTS_READ, WITHDRAWALS_READ, PAY_READ
TREASURY_WRITE	Treasury — everything in treasury read, plus manage sub-accounts and move funds between them	ACCOUNT_BALANCES_READ, TRANSACTION_HISTORY_READ, DEPOSITS_READ, SUB_ACCOUNTS_READ, WITHDRAWALS_READ, PAY_READ, SUB_ACCOUNTS_MANAGE, TRANSFERS_CREATE
WITHDRAWALS_WRITE	Withdrawals — send crypto and fiat, and read withdrawals and balances	WITHDRAWALS_READ, WITHDRAWALS_CREATE, ACCOUNT_BALANCES_READ
BANK_ACCOUNTS_WRITE	Bank accounts — link and remove bank accounts, and onboard and read virtual accounts	BANK_ACCOUNTS_MANAGE, WITHDRAWALS_READ
WEBHOOKS_WRITE	Webhooks — manage webhook subscriptions	WEBHOOKS_READ, WEBHOOKS_MANAGE
VALR_PAY_WRITE	VALR Pay — send and reverse payments, and read payment history and balances	PAY_READ, PAY_SEND, ACCOUNT_BALANCES_READ

Endpoints by permission

Permission	Granted by	Endpoints
ACCOUNT_BALANCES_READ	TRADING_READ, TRADING_WRITE, TREASURY_READ, TREASURY_WRITE, WITHDRAWALS_WRITE, VALR_PAY_WRITE	GET /v1/account/balances GET /v1/account/balances/all
BANK_ACCOUNTS_MANAGE	BANK_ACCOUNTS_WRITE	POST /v1/wallet/fiat/{currency}/accounts DELETE /v1/wallet/fiat/{currency}/accounts/{id}
COLLECTIONS_CREATE	COLLECTIONS_WRITE	POST /v2/wallet/fiat/{currency}/payment/references POST /v2/wallet/fiat/{currency}/payment/bulk-references
COLLECTIONS_DELETE	COLLECTIONS_WRITE	DELETE /v2/wallet/fiat/{currency}/payment/references/{referenceCode} DELETE /v2/wallet/fiat/{currency}/payment/deposits/{publicId}/reference
COLLECTIONS_READ	PAYMENTS_READ, COLLECTIONS_WRITE	GET /v2/wallet/fiat/{currency}/payment/references/{referenceCode} GET /v2/wallet/fiat/{currency}/payment/references GET /v2/wallet/fiat/{currency}/payment/bulk-references/{jobId} GET /v2/wallet/fiat/{currency}/payment/bulk-references/{jobId}/items GET /v2/wallet/fiat/{currency}/payment/deposits GET /v2/payments GET /v2/payments/{id} GET /v2/payments/collect/events GET /v2/payments/collect/events/{id} GET /v2/payments/collect/history GET /v2/payments/collect/runs/{id} GET /v2/payments/collect/runs/{id}/payments GET /v2/payments/collect/runs/history GET /v2/payments/collect/schedules GET /v2/payments/collect/settlements GET /v2/payments/collect/settlements/{id} GET /v2/payments/collect/settlements/{id}/payments GET /v2/payments/collect/settlements/wallet GET /v2/payments/collect/upcoming GET /v2/payments/collections/history
COLLECTIONS_UPDATE	COLLECTIONS_WRITE	PUT /v2/wallet/fiat/{currency}/payment/references/{referenceCode} PUT /v2/wallet/fiat/{currency}/payment/deposits/{publicId}/reference
DEPOSITS_READ	TREASURY_READ, TREASURY_WRITE	GET /v1/wallet/crypto/{currency}/deposit/address GET /v1/wallet/crypto/{currency}/deposit/history GET /v1/wallet/crypto/deposit/history GET /v1/wallet/fiat/{currency}/deposit/reference GET /v1/wallet/fiat/{currency}/deposit/reference/{buyCurrencySymbol} GET /v1/wallet/fiat/{currency}/auto-buy
DISBURSEMENTS_APPROVE	DISBURSEMENTS_WRITE	POST /v2/payments/bulk-withdrawals/batches (also)
DISBURSEMENTS_CREATE	DISBURSEMENTS_WRITE	POST /v2/payments/bulk-withdrawals/batches POST /v2/payments/bulk-withdrawals/beneficiaries POST /v2/payments/bulk-withdrawals/beneficiaries/bulk
DISBURSEMENTS_DELETE	DISBURSEMENTS_WRITE	DELETE /v2/payments/bulk-withdrawals/beneficiaries/{id}
DISBURSEMENTS_READ	PAYMENTS_READ, DISBURSEMENTS_WRITE	GET /v2/payments/bulk-withdrawals/batches/{id} GET /v2/payments/bulk-withdrawals/banks GET /v2/payments/bulk-withdrawals/batches GET /v2/payments/bulk-withdrawals/batches/{id}/fee-quote GET /v2/payments/bulk-withdrawals/batches/{id}/withdrawals GET /v2/payments/bulk-withdrawals/beneficiaries GET /v2/payments/bulk-withdrawals/beneficiaries/{id} POST /v2/payments/bulk-withdrawals/fee-quote GET /v2/payments/bulk-withdrawals/withdrawals GET /v2/payments/payout/history GET /v2/payments/payout/history/{id}
DISBURSEMENTS_UPDATE	DISBURSEMENTS_WRITE	POST /v2/payments/bulk-withdrawals/batches/{id}/cancel PUT /v2/payments/bulk-withdrawals/batches/{id}/label PUT /v2/payments/bulk-withdrawals/beneficiaries/{id}
PAYMENTS_BALANCES_READ	PAYMENTS_READ, COLLECTIONS_WRITE, DISBURSEMENTS_WRITE	GET /v2/payments/account/balances/{type}
SUB_ACCOUNTS_MANAGE	TREASURY_WRITE	POST /v1/account/subaccount PUT /v1/account/subaccount DELETE /v1/account/subaccount
SUB_ACCOUNTS_READ	TREASURY_READ, TREASURY_WRITE	GET /v1/account/subaccounts GET /v1/account/subaccount/{accountPublicId}
TRANSACTION_HISTORY_READ	TRADING_READ, TRADING_WRITE, TREASURY_READ, TREASURY_WRITE	GET /v1/account/transactionhistory GET /v1/account/transactionhistory/subaccounts
TRANSFERS_CREATE	TREASURY_WRITE	POST /v1/account/subaccounts/transfer
WEBHOOKS_MANAGE	WEBHOOKS_WRITE	POST /v1/webhooks DELETE /v1/webhooks/{id} PUT /v1/webhooks/{id}
WEBHOOKS_READ	WEBHOOKS_WRITE	GET /v1/webhooks GET /v1/webhooks/{id} GET /v1/webhooks/{id}/deliveries GET /v1/webhooks/{id}/events/{eventId} GET /v1/webhooks/event-types
WITHDRAWALS_CREATE	WITHDRAWALS_WRITE	POST /v1/wallet/crypto/{currency}/withdraw POST /v1/wallet/fiat/{currency}/withdraw POST /v2/fiat/payments POST /v2/crypto/payments
WITHDRAWALS_READ	TREASURY_READ, TREASURY_WRITE, WITHDRAWALS_WRITE, BANK_ACCOUNTS_WRITE	GET /v1/wallet/crypto/{currency}/withdraw GET /v1/wallet/crypto/{currency}/withdraw/{id} GET /v1/wallet/crypto/{currency}/withdraw/history GET /v1/wallet/crypto/{currency}/withdraw/limits GET /v1/wallet/crypto/address-book GET /v1/wallet/crypto/address-book/{currency} GET /v1/wallet/crypto/service-providers GET /v1/wallet/crypto/withdraw/history GET /v1/wallet/fiat/{currency}/accounts GET /v1/wallet/fiat/{currency}/accounts/{id} GET /v1/wallet/fiat/{currency}/banks GET /v1/wallet/fiat/{currency}/withdraw/estimate-fee GET /v1/wallet/fiat/{currency}/withdrawals GET /v1/wallet/fiat/{currency}/withdrawals/{id}