Skip to main content
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

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. 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. The setting is a report scope preference, not a general grant of child-organization access. See Report execution for request examples and Troubleshooting reports 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 and Service accounts.