> For the complete documentation index, see [llms.txt](https://host2host.onibonje.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://host2host.onibonje.com/docs/06-personas-and-rbac.md).

# Personas and RBAC

## 1. Overview

The platform serves multiple user types with distinct goals, access levels, and interfaces. Role-based access control (RBAC) is scoped by **organization → country → partner → product → environment**.

## 2. Persona Matrix

| Persona                     | Primary Goals                                 | Portal / Interface        | Typical Actions                                         |
| --------------------------- | --------------------------------------------- | ------------------------- | ------------------------------------------------------- |
| Platform Super Admin        | Global governance, environments, policies     | Admin Portal — Global     | Manage countries, environments, global templates, IAM   |
| Country Integration Admin   | Local partner and product setup               | Admin Portal — Country    | Onboard partners, publish country configs               |
| Partner Onboarding Officer  | KYC-style partner setup, connectivity testing | Admin Portal — Onboarding | Create partner drafts, assign credentials, sandbox test |
| Integration Developer       | Complex mappings, new step configs            | Admin Portal — Technical  | Build transforms, route templates, debug flows          |
| Integration Analyst         | Day-to-day mapping and rule changes           | Admin Portal — Config     | Edit mappings, validation rules, schedules              |
| Integration Supervisor      | Approve config changes                        | Admin Portal — Publish    | Review, approve, rollback configurations                |
| Operations / NOC            | Monitor live traffic, handle failures         | Operations Dashboard      | Retry, reprocess, acknowledge alerts                    |
| Reconciliation Analyst      | Match and resolve settlement items            | Recon Workbench           | Manual match, exception resolution                      |
| Corporate Client (External) | Self-service status and file exchange         | Partner Portal            | View status, download ACKs, API docs                    |
| Auditor / Compliance        | Review change and transaction history         | Audit Reports             | Read-only export, config change history                 |
| Security Officer            | Key, cert, and access management              | Security Console          | Vault refs, cert lifecycle, access reviews              |

## 3. Role Definitions

### 3.1 Platform Super Admin

**Scope:** Global (all countries, all partners)

**Permissions:**

* Create and manage country configurations
* Manage environment definitions (sandbox, production)
* Define global route template library
* Manage user roles and assignments
* Configure platform-wide policies (retention, encryption standards)
* Approve high-impact changes (limit policies, global templates)

**Restrictions:** Should not perform day-to-day partner onboarding (delegated to country admins).

### 3.2 Country Integration Admin

**Scope:** Assigned country(ies)

**Permissions:**

* Full partner CRUD within country
* Publish configurations for country partners
* Manage country holiday calendars and cut-offs
* Assign onboarding officers and analysts to partners
* View country operations dashboard

**Restrictions:** Cannot access other countries' partners or configs.

### 3.3 Partner Onboarding Officer

**Scope:** Assigned country, create permissions on partners

**Permissions:**

* Create partner records (DRAFT status)
* Configure channel settings (DRAFT)
* Upload certificates (to Vault via workflow)
* Run sandbox connectivity tests
* Submit configurations for approval

**Restrictions:** Cannot publish to production. Cannot modify published configs directly.

### 3.4 Integration Developer

**Scope:** Assigned country/partner, technical config

**Permissions:**

* Create and edit route templates (DRAFT)
* Create and edit transform specifications
* Access code view in mapping editor
* Run full end-to-end simulation tests
* View Camel route execution traces (debug)

**Restrictions:** Cannot publish without supervisor approval.

### 3.5 Integration Analyst

**Scope:** Assigned partners

**Permissions:**

* Edit mapping specifications (visual editor)
* Edit validation and routing rules
* Manage schedules and cut-offs
* Run transform and validation tests
* Submit changes for approval

**Restrictions:** Cannot create new route templates or step types. Cannot publish.

### 3.6 Integration Supervisor

**Scope:** Assigned country or partner group

**Permissions:**

* Approve or reject pending configurations
* Publish approved configurations
* Rollback to previous config versions
* All read access within scope

**Restrictions:** Cannot modify Vault secrets. Cannot manage IAM.

### 3.7 Operations / NOC

**Scope:** Production environment, assigned countries

**Permissions:**

* View real-time transaction dashboard
* Search transactions by correlation ID, partner, date
* Retry failed transactions (single)
* Send transactions to manual review queue
* Browse and reprocess DLQ messages
* Acknowledge and escalate alerts

**Restrictions:** Cannot modify partner configuration. Bulk reprocess requires supervisor approval workflow.

### 3.8 Reconciliation Analyst

**Scope:** Assigned partners/products

**Permissions:**

* View unmatched reconciliation items
* Perform manual matching
* Categorize exceptions
* Export reconciliation reports

**Restrictions:** Cannot modify integration config or retry payment processing.

### 3.9 Corporate Client (External)

**Scope:** Own partner tenant only

**Permissions:**

* View own transaction status and history
* Download own ACK/NACK files and statements
* Access API documentation and sandbox credentials
* Upload test files (sandbox only)

**Restrictions:** No access to admin portal, other partners, or internal operations.

### 3.10 Auditor / Compliance

**Scope:** Read-only, all or assigned countries (per mandate)

**Permissions:**

* View config audit log (all changes with snapshots)
* View transaction audit trail
* Export reports for regulatory review

**Restrictions:** Strictly read-only. No operational actions.

### 3.11 Security Officer

**Scope:** Security namespace

**Permissions:**

* Manage Vault secret references
* Certificate lifecycle (issue, rotate, revoke)
* Review user access assignments
* Configure IP allowlists and mTLS policies

**Restrictions:** Cannot modify business configuration (mappings, rules).

## 4. RBAC Model

### 4.1 Scope Hierarchy

```
Organization (Bank Group)
  └── Country (NG, GH, KE, ...)
        └── Partner (ACME_CORP)
              └── Product (BULK_PAYMENT, COLLECTION, ...)
                    └── Environment (sandbox, production)
```

### 4.2 Permission Model

Permissions follow the pattern: `{resource}:{action}:{scope}`

**Examples:**

| Permission                    | Description                          |
| ----------------------------- | ------------------------------------ |
| `partner:create:country:NG`   | Create partners in Nigeria           |
| `partner:read:partner:ACME`   | Read ACME partner details            |
| `config:edit:partner:ACME`    | Edit draft configs for ACME          |
| `config:publish:country:NG`   | Publish configs in Nigeria           |
| `operations:retry:country:NG` | Retry failed transactions in Nigeria |
| `audit:read:global`           | Read audit logs globally             |

### 4.3 Role-Permission Mapping

| Role                     | Key Permissions                                                           |
| ------------------------ | ------------------------------------------------------------------------- |
| `PLATFORM_ADMIN`         | `*:*:global`                                                              |
| `COUNTRY_ADMIN`          | `partner:*:country:{assigned}`, `config:publish:country:{assigned}`       |
| `ONBOARDING_OFFICER`     | `partner:create:country:{assigned}`, `config:edit:partner:{assigned}`     |
| `INTEGRATION_DEV`        | `config:edit:country:{assigned}`, `template:*:country:{assigned}`         |
| `INTEGRATION_ANALYST`    | `config:edit:partner:{assigned}`, `transform:*:partner:{assigned}`        |
| `INTEGRATION_SUPERVISOR` | `config:publish:country:{assigned}`, `config:rollback:country:{assigned}` |
| `OPS_NOC`                | `operations:*:country:{assigned}`, `transaction:read:country:{assigned}`  |
| `RECON_ANALYST`          | `recon:*:partner:{assigned}`                                              |
| `PARTNER_USER`           | `transaction:read:partner:{own}`, `file:download:partner:{own}`           |
| `AUDITOR`                | `audit:read:{scope}`, `transaction:read:{scope}`                          |
| `SECURITY_OFFICER`       | `vault:*:global`, `cert:*:global`                                         |

## 5. Identity Provider — Keycloak

### 5.1 Realm Structure

```
heirs-h2h (realm)
├── Internal Users (bank staff)
│   ├── Groups: country-NG, country-GH, ...
│   └── Roles: mapped from section 3
└── External Users (corporate clients)
    ├── Groups: partner-ACME, partner-XYZ, ...
    └── Roles: PARTNER_USER
```

### 5.2 Authentication

| User Type         | Auth Method                              |
| ----------------- | ---------------------------------------- |
| Internal staff    | SSO (SAML/OIDC with bank AD)             |
| External partners | Username/password + MFA, or mTLS for API |
| Service accounts  | Client credentials (machine-to-machine)  |

### 5.3 Session Policy

* Internal: SSO session timeout per bank policy (typically 8 hours)
* External: 30-minute idle timeout, MFA on login
* API: Token-based with short-lived JWT (15 minutes)

## 6. Portal Access Matrix

| Portal               | Personas                                                                           |
| -------------------- | ---------------------------------------------------------------------------------- |
| Admin Portal         | Super admin, country admin, onboarding officer, integration dev/analyst/supervisor |
| Operations Dashboard | NOC, country admin, integration supervisor                                         |
| Recon Workbench      | Recon analyst, country admin                                                       |
| Partner Portal       | Corporate client                                                                   |
| Audit Reports        | Auditor, super admin                                                               |
| Security Console     | Security officer, super admin                                                      |

## 7. Data Isolation

| Isolation Level | Mechanism                                               |
| --------------- | ------------------------------------------------------- |
| Country         | RBAC scope filter on all DB queries                     |
| Partner         | `partner_id` filter; external users see own tenant only |
| Environment     | Sandbox configs never visible to production runtime     |
| Audit           | Immutable append-only log; no delete permissions        |

## 8. Related Documents

* [Low-Code Admin Platform](/docs/05-low-code-admin-platform.md)
* [Security and Compliance](/docs/09-security-and-compliance.md)
* [Multi-Country Deployment](/docs/07-multi-country-deployment.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://host2host.onibonje.com/docs/06-personas-and-rbac.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.