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.

​
Select a child organization with an HQ key

Supported resource GET, POST, PATCH, PUT, and DELETE endpoints accept one organizationId query parameter. Omission keeps the key’s own organization; it does not combine HQ and children automatically.
The same selector works on /clients, /leads, /contacts, /documents, /tasks, /referrals, and the other resource reads marked in the API Reference. It also works on detail and nested reads, for example /cases/CASE_ID/notes?organizationId=CHILD_ORGANIZATION_UUID and /documents/DOCUMENT_ID/content?organizationId=CHILD_ORGANIZATION_UUID. A resource belonging to a different organization still returns 404. For a complete hierarchy extract, query HQ and each child separately and finish pagination for each organization. Send the same organizationId, filters, and that organization’s returned cursor on every page. Cursors are not combined across organizations. Selected GETs return X-Organization-Id identifying the effective organization. Use the organization IDs provided by your administrator; no hierarchy-discovery endpoint is added in this release.

​
Required access for all selected child requests

  • Content downloads require the applicable download grant: library:download for library documents, invoice files, and received medical records; esign:download for e-sign documents. Metadata access alone does not authorize downloading files.
  • The existing endpoint scopes must be present on the key. Selection never adds scopes or bypasses pii:read, medical access, redaction, or audit checks.
  • For a different organization, the key must belong to an active HQ, and the target must be an active descendant (including nested descendants). Parents, siblings outside the HQ tree, and unrelated organizations are denied.
  • The configured acting attorney must be an active member of the key’s HQ and have hq:view_child_orgs. Child membership is not required.
  • Case-based reads also require cases:view, cases:view_all, and hq:view_all_cases. The API Reference lists the additional resource permissions, such as library, calendar, or contact viewing.
  • Financial reads additionally require accounting:view, accounting:view_all, hq:view_all_accounting, and the documented resource permissions.
  • The unified /events feed requires an HQ administrator for child selection; its existing per-entity key-scope filtering still applies. /document-events uses the document permissions.
  • Case-restricted principals (including nsa:only) cannot use these tenant-wide child resource reads. An NSA-enabled target requires nsa:view for case-based reads. Saved reports retain their existing finer-grained NSA authorization.
Permissions and membership are checked on each selected request. An unauthorized or inactive target returns 403 with no fallback to HQ. Invalid, empty, repeated, or comma-separated organizationId values return 400.

​
Creating, updating, and deleting child resources

The same organizationId selector is supported on 95 resource mutations. Use the existing method, body, and headers; for example:
In addition to the read/hierarchy checks above, child mutations require:
  • The endpoint’s existing scope on the key: mutations require the documented write scope; read-only POST actions such as allocation previews retain their read scope. A read-only key cannot write, even when its acting attorney is an HQ administrator.
  • hq:manage_child_orgs and the action permissions listed on that operation in the API Reference. For example, editing and deleting are distinct grants; financial transitions require the documented financial permissions. Endpoints with several possible body-driven actions conservatively require all listed permissions.
  • nsa:edit as well as nsa:view when the selected child enables NSA. Case-restricted principals remain excluded from these broad resource operations.
  • Existing X-Idempotency-Key, If-Match, resource-state, and target-ID checks. Assignees, linked documents, destination folders, and other referenced resources must still satisfy the endpoint’s selected-organization rules.
The configured HQ acting attorney remains the human author/owner, and the key remains the service actor. No child membership is synthesized or reassigned. Idempotency records are partitioned by selected organization, key, and idempotency key; use a stable key per logical operation and repeat the same organization selector when retrying. The legacy case/lead updates that do not support idempotency remain non-idempotent: inspect the result before retrying. For uploads, send the same organizationId when starting and completing the upload. Completion checks both the selected organization and the original key; it cannot commit another child’s upload session. The direct upload URL itself is used as returned. Referral acceptance retains receiving-attorney eligibility: the configured acting attorney must belong to the selected receiving organization and satisfy the canonical referral checks. HQ administration does not impersonate a different receiving attorney. Other referral operations keep sender/receiver and target-case checks. Do not combine organizationId with the legacy case/lead targetOrganizationId body routing field. On referral creation, targetOrganizationId still identifies the recipient, while organizationId selects the sending organization.

​
Coverage and exceptions

Member invitation writes, service-account administration, webhook subscription management, and export jobs remain credential-scoped; selectors are rejected on those operations. organizationIds is supported only on saved-report runs. It is rejected on ordinary resource endpoints rather than silently ignored. The older partner API’s targetOrganizationId write contract is unchanged.

​
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.