Skip to main content
An integration API key is more than a credential: it is a service account — a named, organization-scoped, non-human principal. Everything the key does is recorded against that identity.

​
The model

Writes made through the API are attributed as actorType: "service" with the key’s id and name, plus onBehalfOfAttorneyId when an acting attorney is configured. This attribution flows into the event feed, audit logs, and API responses, so you can always trace a change back to the integration (and person) responsible — and filter out your own writes when consuming the event feed (echo suppression).

​
Acting attorney

The acting attorney is an active member of the key’s organization who provides human attribution for the account’s writes:
  • Required for scopes whose domains need a human owner — document ownership (documents:write), case/lead attribution (cases:write, leads:write), author/sender attribution (notes:write, tasks:write, calendar:write, esign:write), money movement (funds:write), and all elevated PHI/PII scopes. See the full matrix.
  • Required for default HQ report rollups and cross-organization saved report runs. Current report-view/export, hierarchy, and underlying data permissions are checked at execution; selecting an attorney does not grant those permissions.
  • Validated at configuration time: the attorney must be an active organization member.
  • If the acting attorney’s membership is later deactivated, requests that rely on the attribution fail with INTEGRATION_NOT_CONFIGURED until the key is pointed at another active attorney.

​
Lifecycle

  • Create — self-serve in the attorney portal (Settings → Integrations → API Credentials), by a platform admin, or via the API (below). The secret is returned once.
  • Reconfigure — name, standard scopes, acting attorney, report hierarchy preference, and webhook hosts can change without rotating the secret.
  • Rotate — create a new key alongside the old (multiple active keys are supported), migrate, then revoke the old key. There is no in-place secret rotation.
  • Revoke — immediate; revoked keys fail closed.
  • Expire — validUntil is required at creation. Self-serve maximum is 2 years; keys holding elevated (PHI/PII) scopes are capped at 1 year.

​
Management surfaces

​
Attorney portal (self-serve)

Settings → Integrations → API Credentials lists your organization’s keys (name, prefix, scopes, acting attorney, created/expires/last-used, status) and supports create, edit, and revoke. Portal management requires Manage Integrations (integrations:manage); a reporting-only integration usually needs reports:read, not org:manage. Elevated scopes (medical:read, medical:write, pii:read) are visible but disabled — they can only be granted by platform administrators after compliance (BAA) verification, and this restriction is enforced server-side, not just in the UI.

​
API self-management

With the org:manage scope, keys can be managed programmatically — useful for platform partners automating rotation. Note that creating a key additionally requires the calling credential to have an acting attorney configured: API-minted keys are attributed to it, so an org:manage key without one is rejected on POST: Elevated scopes are rejected on this surface too — the same server-side rule as self-serve.
The response contains the new key’s plaintext secret — store it immediately; it is never returned again (idempotent replays of the same request serve a sanitized copy without the secret).
Planned: OAuth 2.0 client-credentials for service accounts — the same scope strings become OAuth scopes on short-lived bearer tokens. Not yet available.

​
HQ report scope

The credential setting reportIncludeChildOrganizations defaults to true, including for existing keys. In the credential editor it is labeled Current organization + child organizations. Set it to false when creating or updating a service account to restrict saved report runs to the key’s organization. Changing this setting does not rotate the secret. Only HQ keys can reach descendants, and only through the acting attorney’s current HQ reporting and data permissions. Configure an acting attorney for HQ rollups. The setting applies to saved report execution, not other endpoints. Explicit organizationIds on a report run must be a subset of the authorized scope. Saved report filters, including case status, remain in effect.

​
Configure a reporting credential

  1. Select the organization that should issue the key. Use HQ for an authorized multi-office report integration.
  2. Create a named integration key with reports:read. Add other scopes only if the integration calls those endpoints.
  3. Choose an existing active acting attorney in HQ and review the HQ reporting permission checklist.
  4. Leave Current organization + child organizations on for HQ rollups, or turn it off for own-organization runs.
  5. Set an expiry, store the one-time secret in the integration’s credential store, and test GET /api/v1/me followed by a known report run. The health check verifies the key; a successful report run verifies the report-specific access.
  6. Review representative records, saved filters, and truncation before scheduling repeated pulls.
To restrict an existing key without rotating it:
Set the property to true to restore the HQ report preference. The acting attorney still needs current authorization. Omitting the property in PATCH preserves its existing value. Setting it does not change the key’s organization, report ownership, saved filters, or access to other API endpoint families.

​
Rotate, revoke, and hand over ownership

Create a replacement key before the old one expires. Configure its scopes, acting attorney, report scope, and webhook hosts deliberately; do not assume a new key copies the old settings. Test it, update the integration’s stored secret, confirm successful requests, then revoke the old credential. Revocation invalidates the old secret; changing a display name does not. Review the acting-attorney assignment when someone changes roles or leaves the organization. Reassign to an appropriate active member and verify report access again. Reconfiguring an acting attorney preserves the secret but can change the permitted reporting data and the meaning of $currentUser report filters. If a secret is lost, create a replacement. List and metadata endpoints cannot recover it. Use the prefix, name, expiry, and last-used time to identify a credential without sharing its secret.