Access Control & Permissions
Document ID: ACP-001 Version: 1.0 Classification: Internal / Regulator-Shareable Effective Date: March 2026 Next Review: September 2026 Owner: Keshless Security Team
1. Purpose
This document provides a comprehensive breakdown of all access control mechanisms, role-based permissions, and authorization policies implemented across the Keshless digital wallet platform. It serves as the authoritative reference for:
- Regulatory audits (Central Bank of Eswatini, FSA)
- Partner due diligence (banks, telcos, payment processors)
- Internal governance (team reference for who can do what, where, and why)
2. Regulatory Compliance Mapping
Keshless access controls are designed to satisfy the following regulatory requirements:
| Regulation | Requirement | How Keshless Complies | Reference |
|---|---|---|---|
| FATF Recommendation 10 | Customer Due Diligence | KYC verification gates wallet operations; tiered access by verification level | Data Access Controls |
| FATF Recommendation 15 | New Technologies | Device-based auth for vendors; API key management for integrations | Authentication |
| FATF Recommendation 20 | Suspicious Transaction Reporting | Compliance Officer role with SAR filing permissions; audit trail | Roles & Permissions |
| Eswatini FSA | Operator Licensing Conditions | Segregation of duties via role hierarchy; emergency kill switches | Emergency Controls |
| POPIA Section 19 | Security Safeguards | Encryption at rest/transit; row-level data isolation; access logging | Data Access Controls |
| PCI DSS Req. 7 | Restrict Access by Business Need | Granular permission system (90+ permissions); least-privilege defaults | Roles & Permissions |
| PCI DSS Req. 8 | Identify & Authenticate Access | JWT + OTP + PIN; password complexity; account lockout | Authentication |
| PCI DSS Req. 10 | Track & Monitor Access | SHA-256 hash-chained audit logs; activity logging | Data Access Controls |
3. Access Control Architecture
┌──────────────────────────────────────────────────────────────────────┐
│ ACCESS CHANNELS │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────┐ ┌──────────┐ │
│ │ User App │ │ Vendor │ │ Admin │ │ USSD │ │ Partner │ │
│ │ (Flutter)│ │ App │ │ Dashboard│ │ │ │ API │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └──┬───┘ └────┬─────┘ │
└───────┼──────────────┼──────────────┼───────────┼───────────┼────────┘
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
┌──────────────────────────────────────────────────────────────────────┐
│ AUTHENTICATION LAYER │
│ │
│ JWT Bearer JWT Bearer JWT Bearer PIN + Session API Key │
│ + OTP + Device ID + Password + IP Whitelist + IP WL │
│ │
│ See: authentication.md │
└──────────────────────────────┬───────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────┐
│ AUTHORIZATION LAYER │
│ │
│ ┌─────────────────┐ ┌──────────────────┐ ┌───────────────────┐ │
│ │ Role Check │ │ Permission Check │ │ Ownership Check │ │
│ │ (9 admin roles, │ │ (90+ granular │ │ (user owns data, │ │
│ │ 5 vendor roles)│ │ permissions) │ │ vendor scoping) │ │
│ └─────────────────┘ └──────────────────┘ └───────────────────┘ │
│ │
│ See: roles-and-permissions.md, data-access-controls.md │
└──────────────────────────────┬───────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────┐
│ SAFETY LAYER │
│ │
│ ┌─────────────────┐ ┌──────────────────┐ ┌───────────────────┐ │
│ │ Emergency │ │ Rate Limiting │ │ KYC Gating │ │
│ │ Kill Switches │ │ (per-IP, per- │ │ (verification │ │
│ │ (8 controls) │ │ user, per-phone)│ │ status gates ops) │ │
│ └─────────────────┘ └──────────────────┘ └───────────────────┘ │
│ │
│ See: emergency-controls.md, data-access-controls.md │
└──────────────────────────────────────────────────────────────────────┘4. Access Control Summary
4.1 Principal Types
Keshless recognizes five types of principals (authenticated entities):
| Principal | Auth Method | Access Scope | Detailed Reference |
|---|---|---|---|
| End User | OTP + JWT | Own wallet, transactions, profile | Authentication |
| Vendor | Email/Password + Device ID + JWT | Own business data, sub-user management | Authentication |
| Admin Employee | Email/Password + JWT | Dashboard operations per assigned permissions | Roles & Permissions |
| USSD User | Phone number + PIN | Balance, transfers, withdrawals, airtime | Authentication |
| Integration Partner | API Key + IP Whitelist | Vendor-scoped operations | Integration Security |
4.2 Permission Model
| Layer | Mechanism | Granularity | Count |
|---|---|---|---|
| Admin Permissions | RBAC with 9 role templates + custom | Per-action (view, edit, approve, delete) | 90+ permissions |
| Vendor Permissions | RBAC with 5 role templates + custom | Per-action (transactions, reports, cards) | 27 permissions |
| Emergency Controls | System-wide kill switches | Per-operation category | 8 controls |
| Data Scoping | Ownership + tenant isolation | Per-record | Row-level |
4.3 Key Security Properties
- Least Privilege: All roles default to minimum permissions; CUSTOM role starts empty
- Segregation of Duties: Only SUPER_ADMIN can create other admins; COMPLIANCE_OFFICER cannot modify financial configs
- Defense in Depth: Auth → Role → Permission → Ownership → Emergency controls (5 layers)
- Fail Closed: Missing token = denied; missing permission = denied; DB unavailable = all requests rejected
- Audit Everything: All admin actions logged with SHA-256 hash chain for tamper detection
5. Section Documents
| Document | ID | Contents |
|---|---|---|
| Authentication Mechanisms | ACP-001.1 | JWT, OTP, PIN, API Key, device auth — all authentication flows |
| Roles & Permissions | ACP-001.2 | Complete RBAC breakdown, permission matrices, role templates |
| Data Access Controls | ACP-001.3 | Ownership, tenant isolation, KYC gating, audit trail |
| Emergency Controls | ACP-001.4 | Kill switches, rate limiting, incident activation |
| Integration Security | ACP-001.5 | Partner API keys, IP whitelisting, vendor-scoped access |
6. Document Version Control
| Version | Date | Author | Changes |
|---|---|---|---|
| 1.0 | March 2026 | Keshless Security Team | Initial comprehensive access control documentation |
7. Contact
- Security Officer: compliance@keshless.app
- Incident Reporting: security@keshless.app
- Partner Integration Inquiries: integrations@keshless.app