# Power BI permissions and approval matrix

## Human roles in the existing application

| Permission | Purpose | Default |
| --- | --- | --- |
| `api_integrations.view` | Existing integrations overview | Existing assignment preserved |
| `api_integrations.view_api_urls` | Existing URL catalogue | Existing assignment preserved |
| `api_integrations.manage_clients` | Existing client-management screen | Existing assignment preserved |
| `api_integrations.manage_powerbi_clients` | Additional gate for any Power BI client creation/configuration | Denied for existing roles by migration |
| `api_integrations.grant_powerbi_national` | Additional approval to grant national extraction | Denied for existing roles by migration |
| `api_integrations.view_logs` | Existing sharing/audit metadata screens | Existing assignment preserved |
| `roles.configure` | Existing permission-administration screen | Existing assignment preserved |
| `data_scope.national/district/partner/own_records` | Grantor's own permitted data coverage | Existing assignment preserved |

Grant only approved operator roles. A national operator needs national data scope
as well as both management permissions and the national approval permission.
A scoped operator must restrict the client to their own assigned scope; all
their active district, partner and ownership restrictions are required. There
is no role-name, role-ID or administrator-email bypass in the new API client
policy. The application's existing explicitly configured emergency human-role
bypass remains an operational control requiring separate governance.

The migration records the two new permissions in `role_permissions` with
`is_allowed=0` for each existing role. Future roles see these definitions through
the existing permission registry and need an explicit assignment. Permission
registration is not permission approval.

## Machine client scopes

Minimum example for a district's survivor and incident analysis:

```text
powerbi.manifest.read,powerbi.schema.read,powerbi.survivors.read,powerbi.incidents.read,data_scope.district
```

Assign the district IDs through the existing Allowed Districts selector. For
actions/services/status history, add only the necessary feed scopes:

```text
powerbi.actions.read,powerbi.action_services.read,powerbi.case_status_history.read
```

Perpetrator/witness feeds require their own explicit permissions and capacity
approval because their current volumes are very large:

```text
powerbi.perpetrators.read,powerbi.witnesses.read
```

Use `data_scope.partner` with one assigned partner for a partner-specific client;
use `data_scope.own_records` only when the client creator is the intended record
owner. National scope must be approved explicitly. Combining scopes intersects
restrictions. Nonempty district/partner assignments remain restrictive even if
national scope is also present. `*` and `data_scope.*` are rejected.

Separate clients by consuming system, approved dataset and geographic purpose.
Do not reuse UBOS/NSR/Sauti client credentials. Credentials expire after 90 days;
replace them through the current create/disable workflow. No new screen layout
or hidden unrestricted reporting account is introduced.

## Database roles

| Role | Required privileges | Excluded privileges |
| --- | --- | --- |
| Source reader on reporting replica | SELECT on the listed operational/reference tables; REPLICATION CLIENT for health/lag | Source INSERT/UPDATE/DELETE/ALTER, account administration, replication configuration |
| Snapshot migrator | CREATE/ALTER/INDEX on the dedicated snapshot schema during deployment | Production case-schema DDL |
| Snapshot publisher/pruner | SELECT/INSERT/UPDATE/DELETE on the three snapshot tables; normal named-lock use | Source writes and production schema DDL |
| API snapshot reader | SELECT on the three snapshot tables | Snapshot writes and source access |
| Existing application account | Existing client/permission access; safe integration audit INSERT | No new case-table grants are added |

Run the snapshot migration using a temporary migrator credential, then replace
the store credential with the publisher account. Restrict host grants to the
actual application/worker addresses and require database TLS for remote hosts.

## Power BI workspace

API client scopes apply to the extraction account, not every report viewer.
Configure Power BI workspace access, row-level security, Build/export permissions,
gateway ownership, retention and device controls separately. Disable public
publishing and prohibit plaintext credentials in PBIX/M/source-control files.
Removing API access does not erase records previously imported into a model.
