Wallet API Permissions - Restructuring Summary¶
Overview¶
Restructured all wallet API permissions to use resource-first naming convention (e.g., create_wallet instead of wallet.create).
📋 Permissions Added to backend/seed/permissions.json (18 total)¶
| Permission Name | Title | Description |
|---|---|---|
create_wallet |
Create Wallet | Permission to create a new wallet |
read_wallet |
Read Wallet | Permission to read wallet details, balance, and statements |
update_wallet |
Update Wallet | Permission to update wallet configuration, status, and KYC |
topup_wallet |
Topup Wallet | Permission to process wallet top-ups |
transfer_wallet |
Transfer Wallet | Permission to perform P2P wallet transfers |
withdraw_wallet |
Withdraw Wallet | Permission to process wallet withdrawals |
verify_wallet_kyc |
Verify Wallet KYC | Permission to verify wallet KYC status |
reverse_transaction |
Reverse Transaction | Permission to reverse wallet ledger entries and transactions |
adjust_balance |
Adjust Balance | Permission to manually adjust wallet balance |
manage_linked_accounts |
Manage Linked Accounts | Permission to add, update, and remove linked bank accounts |
reconcile_wallet_balance |
Reconcile Wallet Balance | Permission to reconcile wallet balance from ledger |
freeze_wallet |
Freeze Wallet | Permission to freeze/unfreeze wallet debits and credits |
generate_qr_codes |
Generate QR Codes | Permission to generate wallet QR codes |
process_qr_payments |
Process QR Payments | Permission to process payments from QR codes |
set_wallet_pin |
Set Wallet PIN | Permission to set wallet PIN for the first time |
change_wallet_pin |
Change Wallet PIN | Permission to change existing wallet PIN |
reset_wallet_pin |
Reset Wallet PIN | Permission to reset wallet PIN (admin action) |
download_statement |
Download Statement | Permission to download and email wallet statements |
🎯 Actions Added to backend/seed/actions.json (18 total)¶
Each action maps to one permission and is used by the permission assignment system: - Create Wallet - View Wallet - Update Wallet - Topup Wallet - Transfer Wallet - Withdraw Wallet - Verify Wallet KYC - Reverse Transaction - Adjust Balance - Manage Linked Accounts - Reconcile Wallet Balance - Freeze Wallet - Generate QR Codes - Process QR Payments - Set Wallet PIN - Change Wallet PIN - Reset Wallet PIN - Download Statement
📁 Category Added to backend/seed/category.json¶
"Manage Wallets" category created containing all 18 wallet actions for role-based permission management.
🔄 Backend Changes - backend/routers/wallet.py¶
Permission Mappings Updated¶
| Old Permission | New Permission | Affected Endpoints |
|---|---|---|
wallet.create |
create_wallet |
/create |
wallet.read |
read_wallet |
/wallet/get, /wallet/owner, /wallet/by-phone, /balance/fetch, /balance/currency, /wallet/config, /wallet/fetch, /wallet/detail, /transaction/validate, /linked-accounts/list, /linked-accounts/get, /statement, /statement/export, /statement/email, /balance/reconciliation-history, /freeze/status, /freeze/log, /ledger/entries |
wallet.update |
update_wallet |
/config/update, /balance/add-currency, /wallet/status/update, /wallet/kyc/approve, /wallet/config/update |
wallet.topup |
topup_wallet |
/transaction/topup |
wallet.transfer |
transfer_wallet |
/transaction/transfer |
wallet.withdraw |
withdraw_wallet |
/transaction/withdraw |
wallet_verify |
verify_wallet_kyc |
/kyc/verify |
wallet_read |
read_wallet |
/wallet/config |
wallet.reverse |
reverse_transaction |
/transaction/reverse |
wallet.adjust |
adjust_balance |
/transaction/adjust |
wallet.manage_bank_accounts |
manage_linked_accounts |
/linked-accounts/add, /linked-accounts/update, /linked-accounts/remove, /linked-accounts/verify/initiate, /linked-accounts/verify/confirm, /linked-accounts/set-default |
wallet.reconcile |
reconcile_wallet_balance |
/balance/reconcile |
wallet.freeze |
freeze_wallet |
/freeze |
wallet.generate_qr_codes |
generate_qr_codes |
/qr-code/generate/payment-request |
wallet.process_qr_payments |
process_qr_payments |
/qr-code/process |
wallet.pin.set |
set_wallet_pin |
/pin/set |
wallet.pin.change |
change_wallet_pin |
/pin/change |
wallet.pin.reset |
reset_wallet_pin |
/pin/reset |
Endpoints WITHOUT Permissions (Left Untouched)¶
As requested, endpoints without permission_required decorator were left alone:
- /qr-code/generate/merchant (POST)
- /qr-code/generate/p2p (POST)
- /qr-code/scan (POST)
- /qr-code/details (POST)
- /qr-code/list (POST)
- /qr-code/deactivate (POST)
- /qr-code/image (GET)
🎨 Frontend Changes - ui/src/modules/wallet/redux/actions.ts¶
Redux Actions Updated (22 total)¶
All wallet Redux actions updated with new permission names:
| Action | Old Permission | New Permission |
|---|---|---|
getWalletDetail |
wallet.read |
read_wallet |
updateWalletStatus |
wallet.update |
update_wallet |
approveWalletKyc |
wallet.update |
update_wallet |
updateWalletConfig |
wallet.update |
update_wallet |
reconcileBalance |
wallet.reconcile |
reconcile_wallet_balance |
getReconciliationHistory |
wallet.read |
read_wallet |
setWalletFreeze |
wallet.freeze |
freeze_wallet |
getWalletFreezeStatus |
wallet.read |
read_wallet |
getWalletFreezeLog |
wallet.read |
read_wallet |
addLinkedBankAccount |
wallet.manage |
manage_linked_accounts |
listLinkedBankAccounts |
wallet.read |
read_wallet |
removeLinkedBankAccount |
wallet.manage |
manage_linked_accounts |
setDefaultLinkedAccount |
wallet.manage |
manage_linked_accounts |
initiateVerification |
wallet.manage |
manage_linked_accounts |
confirmVerification |
wallet.manage |
manage_linked_accounts |
adjustBalance |
wallet.admin |
adjust_balance |
reverseTransaction |
wallet.admin |
reverse_transaction |
getLedgerEntries |
wallet.read |
read_wallet |
setWalletPin |
wallet.pin.set |
set_wallet_pin |
changeWalletPin |
wallet.pin.change |
change_wallet_pin |
resetWalletPin |
wallet.pin.reset |
reset_wallet_pin |
addCurrencyBalance |
wallet.update |
update_wallet |
🔐 Frontend UI Changes - ui/src/modules/wallet/pages/Wallet/blocks/wallet_detail.tsx¶
Permission Guards Added to Buttons¶
Added hasPermission() checks to the following wallet detail page buttons:
- "Update Status" button →
update_walletpermission - "Manage KYC" button →
update_walletpermission - "Edit Config" button →
update_walletpermission - "Add Currency" button →
update_walletpermission - "Statement" button →
download_statementpermission (already existed)
Permission Checks in Sub-Components¶
The following sub-components handle their own permissions internally:
- ReconciliationPanel → reconcile_wallet_balance
- FreezePanel → freeze_wallet
- PinManagementPanel → set_wallet_pin, change_wallet_pin, reset_wallet_pin
- LinkedAccountsPanel → manage_linked_accounts
- BalanceAdjustmentPanel → adjust_balance
- LedgerEntriesPanel → reverse_transaction
✅ Verification Checklist¶
- [x] All wallet permissions added to permissions.json with resource-first naming
- [x] All wallet actions created in actions.json
- [x] "Manage Wallets" category created in category.json
- [x] Backend wallet.py updated with new permission names (37 endpoints)
- [x] Frontend Redux actions updated (22 actions)
- [x] Wallet detail page buttons protected with permission checks (5 buttons)
- [x] Sub-component permission handling validated
- [x] Unsecured endpoints (without permission_required) left untouched (7 endpoints)
📝 Naming Convention Applied¶
Resource-First Format: <action>_<resource>
Examples:
- ✅ create_wallet (not wallet_create or wallet.create)
- ✅ read_wallet (not wallet_read or wallet.read)
- ✅ adjust_balance (not balance_adjust)
- ✅ reverse_transaction (not transaction_reverse)
- ✅ manage_linked_accounts (not linked_accounts_manage)
🚀 Next Steps¶
- Database Migration: Run seed scripts to populate new permissions
- Role Assignment: Map new permissions to existing roles
- Testing: Verify permission enforcement on all wallet endpoints
- Documentation: Update API documentation with new permission names
- Monitoring: Monitor for any permission-related errors after deployment
📞 Notes¶
- All changes are backward compatible at the code level (only permission strings changed)
- Database migration required to add new permission records
- Frontend already dispatches actions with embedded permissions - no additional changes needed
- Old permission strings should be removed from roles after transition to new names