---
title: "Get Permissions Usage"
method: GET
path: "/internal/permissions/usage"
tags: ["internal"]
---

# Get Permissions Usage

`GET /internal/permissions/usage`

Global view of every permission and all roles that grant it.

Unlike ``/roles/matrix`` (scoped to system roles or a single company), this
aggregates role usage across all companies and system roles so a permission's
full footprint is visible in one place.

## Response `200`

Successful Response

- PermissionUsageResponse
  - `modules` ModulePermissionUsage[], required
    - `module_name` string, required
    - `entities` EntityPermissionUsage[], required
      - `entity_name` string, required
      - `permissions` PermissionUsageEntry[], required
        - `permission_id` string, required
        - `permission_name` string, required
        - `description` string, nullable, required
        - `roles` RoleUsage[], required
          - `role_id` string, required
          - `role_name` string, required
          - `company_id` string, nullable, required
          - `company_name` string, nullable, required
          - `archetype` 'tprm_admin' | 'business_owner' | 'tprm_analyst' | 'sme' | 'view_only' | 'collateral_admin' | 'collateral_reviewer' | 'collateral_submitter' | 'policy_reviewer' — Closed, product-owned set of role identities. Stable machine keys — never renamed.

---

[API](https://skmtc.dev/kobaltlabs/apis/fastapi.md) · [All operations](https://skmtc.dev/kobaltlabs/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/kobaltlabs/fastapi/revisions/3ff4c0bd276b/schema)