> ## Documentation Index > Fetch the complete documentation index at: https://www.presolve.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Organizations, HQ, and permissions > How integration-key scopes, organization boundaries, acting attorneys, and reporting RBAC work together. An HQ organization, an API key, and an administrator role describe different kinds of access. Check each one when configuring an integration. A key belonging to HQ is not automatically a credential for every endpoint in every child organization. ## The access controls | Control | What it determines | | - | - | | Key validity | Whether the secret is active, unexpired, and accepted by the endpoint | | Key scopes | Which API operations the integration may call, such as `reports:read` or `org:manage` | | Key organization | The organization that issued the credential | | Acting attorney | The active member used for attribution and for permission checks on operations that require a human principal | | Organization roles (RBAC) | The acting attorney's current permissions for HQ reporting and the underlying data | | Report access and filters | Whether the saved definition is available, and which authorized records match it | API scope strings and organization-role permissions are separate. For example, a key's `reports:read` scope allows it to call reporting endpoints. The acting attorney's `reports:view` and `reports:export` permissions are additional checks for HQ report execution. Granting one does not grant the other. An acting attorney does not make every endpoint inherit all of that person's application access. Each endpoint still enforces its key scopes and organization boundary. ## Choose the acting attorney Use an existing active member of the organization that owns the key. Selecting that member does not require creating another account in each child organization for an authorized HQ report rollup. The acting attorney has two jobs: * Attribute supported writes to a named person while the integration remains the service actor in audit records. * Supply current reporting and data permissions when executing reports across the HQ hierarchy. For ordinary attribution-dependent operations, a missing or inactive member can produce `INTEGRATION_NOT_CONFIGURED`. For default HQ report runs, missing acting-attorney configuration or insufficient hierarchy permissions produces `403`. Changing the key's name or knowing a report ID does not resolve either condition. ## HQ saved-report permissions The following applies to `POST /api/v1/reports/{reportId}/run` when it uses child organizations, a child-owned report, or the default HQ rollup. | Requirement | Permission or setting to check | | - | - | | API operation | Integration key has `reports:read` | | Hierarchy enabled | Key's **Current organization + child organizations** toggle is on | | Human principal | Configured acting attorney is an active member of the key's HQ organization | | Reporting | Acting attorney has View Reports (`reports:view`) and Export Reports (`reports:export`) | | Hierarchy visibility | View Child Organizations (`hq:view_child_orgs`) | | Case-based data | Case viewing plus the applicable broad case permissions; child rows require `hq:view_all_cases` | | Accounting-based data | The report data source's accounting permissions; child accounting dependencies require `hq:view_all_accounting` | | Mixed reports | Both case and accounting grants when the report references both domains | | NSA records | Applicable case permissions and NSA View (`nsa:view`); NSA-only restrictions still apply | | Child report definition | Within the authorized hierarchy, shared, and API-visible | Roles have configurable names. A role named “Reporting” or “HQ Admin” is not itself evidence of these grants; review its permissions. Enabled practice areas and other data restrictions also matter. Permissions are checked during execution. If access is removed, the key does not retain an earlier reporting grant. A default HQ rollup fails rather than silently becoming an HQ-only result when the required HQ access is lost. ## What the HQ toggle covers `reportIncludeChildOrganizations` defaults to `true` for existing and new integration keys. For HQ saved report runs, omitting `organizationIds` requests the current organization and authorized descendants. Send a comma-separated subset to narrow the request. Turn the toggle off to restrict the key's saved report runs to its own organization. | Surface | Effect of this toggle | | - | - | | v1 saved report run | Can include authorized HQ and descendant data, including supported accounting reports | | v1 report list and definition metadata | Remain scoped to the key's organization | | v1 export jobs | Remain scoped to the key's organization | | v1 accounting, cases, leads, and other resource endpoints | Their existing organization boundaries remain in effect | | Accounting, Lead Overview, report viewers, and dashboards in the application | Use the signed-in member's existing HQ/RBAC and page-specific scope controls; the key toggle does not change them | | Legacy report API | Uses its separate reporting credential and legacy scope rules | The setting is a report scope preference, not a general grant of child-organization access. See [Report execution](/docs/reporting/report-definitions) for request examples and [Troubleshooting reports](/docs/reporting/troubleshooting) for missing data. ## Who may manage access Portal key management requires **Manage Integrations** (`integrations:manage`). API-based key management requires `org:manage`; creating another key also requires the calling credential to have an acting attorney configured. These are powerful management capabilities, separate from the scope needed to run a report. Elevated scopes are granted by platform administrators. An organization administrator cannot add them through the self-service key API. See [Scopes](/docs/scopes) and [Service accounts](/docs/service-accounts).