Skip to main content
Every request to the public API is authenticated with an integration API key, sent in the x-api-key header:
A missing or invalid key returns 401:

​
Creating a key

Members with Manage Integrations create integration keys in the attorney portal under Settings → Integrations → API Credentials (requires the integrations-management permission). At creation you choose:
  • a name (surfaced as the actor name in events and audit logs),
  • the scopes the key holds (see Scopes — standard scopes only; elevated PHI/PII scopes are admin-granted),
  • an acting attorney — required when the selected scopes need one (see the scope ↔ acting-attorney matrix),
  • an expiry (validUntil is required; maximum 2 years, or 1 year for keys holding elevated scopes),
  • for reporting, Current organization + child organizations — on by default; HQ rollups require the acting attorney’s current HQ reporting and data permissions,
  • optionally, webhook allowed hosts — the HTTPS host allowlist for webhook subscription URLs.
The plaintext secret is shown exactly once, at creation. Only a SHA-256 digest and a short prefix are stored; the prefix is displayed in the UI and in GET /me so you can tell keys apart. Keys can also be managed programmatically with the org:manage scope via the /service-accounts endpoints — see Service accounts.

​
Key lifecycle

  • Multiple active keys per org. Keys are additive and independently revocable, which is what makes zero-downtime rotation possible: create a new key, migrate your integration, then revoke the old one.
  • Reconfiguration without rotation. Name, standard scopes, acting attorney, report hierarchy preference, and webhook hosts can be changed without touching the secret.
  • Revocation takes effect immediately; revoked and expired keys fail closed.
  • Expiry is mandatory — plan rotation before expiresAt (visible in GET /me).

​
Scope enforcement

Most endpoints declare a single required scope (shown in the API Reference as x-required-scope). The exceptions: GET /me requires no scope at all (it is the credential health check), and a few endpoints accept a legacy alternative for backwards compatibility (e.g. GET /cases honors documents:read where cases:read is the primary scope). A key without the required scope receives 403:
Scopes are explicit grants — write never implies read, and there are no wildcard scopes.

​
Acting attorney

Some scopes require the key to be configured with an acting attorney (an active member of your organization). Writes made by such a key are attributed to the service account acting on behalf of that attorney — this is how document ownership, note/task/e-sign authorship, and compliance attribution work. If the acting attorney’s membership is deactivated, affected requests fail with INTEGRATION_NOT_CONFIGURED until the key is reconfigured. The acting attorney is not a substitute for API scopes. For HQ reporting, current organization roles determine which descendant data the key may read. For other endpoints, their existing key scopes and organization boundaries still apply. See Organizations, HQ, and permissions.

​
Tenancy

Queries, mutations, and event reads normally stay within the key’s organization. Saved report runs (POST /api/v1/reports/{reportId}/run) can also include authorized descendants of an HQ organization. The Current organization + child organizations credential toggle (reportIncludeChildOrganizations) defaults to on for existing and new keys. Hierarchy reporting requires an acting attorney with current HQ visibility, report viewing/export, and the report’s data permissions. The toggle does not grant permissions. Default HQ rollups return 403 if the acting attorney is missing or no longer authorized, rather than silently shrinking to HQ-only data. Turn it off to restrict report runs to the key’s own organization. For report runs, pass ?organizationIds=<org-id>,<child-id> to select a narrower authorized scope. Unauthorized IDs return 403; shared child reports must also be API-visible, otherwise 404. Incompatible field definitions return 400. The report owner’s fields and saved filters still apply. Report listing, metadata lookup, and export jobs remain scoped to the key’s own organization.

​
Legacy partner credentials

Two endpoint families predate integration keys and continue to accept partner API keys and OIDC bearer tokens (Authorization: Bearer <token>) unchanged: case create/update (POST /cases, PATCH /cases/{caseId}) and lead create/update (POST /leads, PATCH /leads/{leadId}). Integration keys work on those endpoints too, with scope enforcement (cases:write / leads:write). All other /api/v1 endpoints require an integration key; bearer tokens are rejected there today.
Planned: an OAuth 2.0 client-credentials flow issuing short-lived bearer tokens, using the same scope vocabulary. It has not shipped; the x-api-key header is the supported authentication method.

​
Request checklist

  1. Send x-api-key on every request.
  2. Send X-Idempotency-Key on mutations (any stable unique string up to 200 chars, e.g. a UUID per logical operation). Each operation’s API Reference entry says whether it consumes the header. Exceptions that ignore it — do not blind-retry these: POST /leads, PATCH /leads/{leadId}, and PATCH /cases/{caseId}; retrying a timed-out call there can create duplicate records, so confirm outcome with a read first.
  3. Send If-Match: "<revision>" when updating revisioned entities (documents, folders), using the last ETag you saw.
  4. Watch X-RateLimit-Remaining and back off on 429 per Retry-After.