Scopes

Scopes authorize what an integration API key may do. Most endpoints require a single scope (named in the API Reference as x-required-scope); a key without it receives 403 FORBIDDEN. Two kinds of exception exist: GET /me requires no scope (credential health check), and a few endpoints accept a legacy alternative for backwards compatibility (e.g. GET /cases honors documents:read alongside cases:read).

Format

Scopes are <resource>:<verb>, all lowercase:

Verb	Meaning
`read`	GET endpoints for the resource, including list/search and sub-resources
`write`	Create, update, state transitions, soft-delete/restore
`manage`	Configuration/administrative surfaces (e.g. webhook subscriptions, key self-management)

Rules:

A verb never implies another — write does not imply read. Keys are granted explicit lists.
There are no wildcard scopes (*, cases:*) — explicit grants only.
Scopes gate endpoints, and in two cases gate fields (pii:read) or an entire elevated domain (medical:*) — see below.

Standard scopes

Resource	Scopes	Covers
`cases`	`cases:read`, `cases:write`	Cases/matters, turn-down requests, tags, case history, case attorneys
`leads`	`leads:read`, `leads:write`	Case leads, lead status transitions, turn-downs, lead status definitions
`clients`	`clients:read`, `clients:write`	Plaintiffs/clients and their relationships
`contacts`	`contacts:read`, `contacts:write`	Contacts, case-contact assignments, assignment types
`documents`	`documents:read`, `documents:write`	Files & folders, presigned uploads, versions, tags, batch operations, share links
`notes`	`notes:read`, `notes:write`	Case notes
`tasks`	`tasks:read`, `tasks:write`	Tasks, assignment, completion, snooze, followers
`calendar`	`calendar:read`, `calendar:write`	Non-task calendar items (events/appointments)
`deadlines`	`deadlines:read`, `deadlines:write`	Deadline obligations and anchors; rule packs are read-only
`intake`	`intake:read`, `intake:write`	Survey details (custom intake fields) per case; question sets are read-only
`esign`	`esign:read`, `esign:write`	E-sign documents: send, status, download, remind, cancel
`billing`	`billing:read`, `billing:write`	Liens, expenses, time entries, invoices
`funds`	`funds:read`, `funds:write`	Settlement money movement: resolutions (read), checks, allocations, disbursement transitions, available funds. Kept separate from `billing` because it moves real money and warrants narrower grants
`referrals`	`referrals:read`, `referrals:write`	Case referrals, accept/decline, activities
`communications`	`communications:read`, `communications:write`	Case emails (append-only logging) and call logs
`org`	`org:read`, `org:manage`	Organization profile, members, roles (read); invites and service-account key self-management (manage)
`reports`	`reports:read`	Saved report listing and execution, data-export jobs
`events`	`events:read`	The unified event feed (`GET /events`) and event-type discovery
`webhooks`	`webhooks:manage`	Webhook subscription CRUD

Note: documents:read, documents:write, and webhooks:manage predate the rest of the vocabulary; existing keys holding them keep working unchanged, and documents:read is still honored on GET /cases (the original document-sync inventory endpoint) alongside cases:read.

Elevated scopes (PHI/PII)

These scopes are never bundled and never implied by any standard scope, and are admin-granted only — they can be added to a key exclusively by platform administrators after BAA verification. Self-serve create/update requests that include them are rejected server-side.

Scope	Gates
`medical:read`	All medical-domain endpoints (facilities, treatment summaries, retrieval requests) and medical document content
`medical:write`	Medical-domain mutations
`pii:read`	PII fields on otherwise-standard responses: SSN, date of birth, and the rest of the sensitive-field set. Without it, `cases:read` / `clients:read` / `intake:read` responses omit (not blank) these fields

Any key holding an elevated scope additionally requires:

an acting attorney (every PHI access is attributable to a person),
HIPAA audit entries written for every read of a gated endpoint or field,
a shorter maximum expiry (1 year) and the sensitive rate tier (60/min).

Scope ↔ acting-attorney matrix

Scope	Acting attorney
`documents:write`	Required (document ownership)
`cases:write`, `leads:write`	Required (case/lead attribution, assignment defaults)
`notes:write`, `tasks:write`, `calendar:write`, `esign:write`	Required (author/sender attribution)
`medical:read`, `medical:write`, `pii:read`	Required (compliance attribution)
`funds:write`	Required (money-movement attribution)
`referrals:write`	Required (referral acceptance is attributed to the acting attorney)
`org:manage`	Optional for reads/updates; required to create keys (`POST /service-accounts` attributes creation to it)
`reports:read`	Required for default HQ rollups and cross-organization saved report runs; otherwise optional
Other non-elevated `:read` scopes, `billing:*`, `intake:write`, `communications:write`, `deadlines:write`, `webhooks:manage`	Optional

Scopes and organization roles

The key scope reports:read is separate from the acting attorney’s organization permissions reports:view, reports:export, and applicable hq:* and data permissions. A hierarchy toggle is not an additional API scope and does not grant a role. See the HQ reporting checklist. org:manage controls administrative API operations, including key management. It is not required just to execute reports, and it does not make all resource endpoints cross-organization. Portal credential management uses the separate organization permission integrations:manage.

Choosing scopes

Grant the minimum set your integration needs, and split responsibilities across keys where practical — keys are cheap, independently revocable, and each carries its own rate-limit budget and webhook subscriptions. A typical read-only sync integration needs only events:read plus the :read scopes of the entities it mirrors.

Getting started

Events & webhooks

Reporting

Format

Standard scopes

Elevated scopes (PHI/PII)

Scope ↔ acting-attorney matrix

Scopes and organization roles

Choosing scopes

​Format

​Standard scopes

​Elevated scopes (PHI/PII)

​Scope ↔ acting-attorney matrix

​Scopes and organization roles

​Choosing scopes

Format

Standard scopes

Elevated scopes (PHI/PII)

Scope ↔ acting-attorney matrix

Scopes and organization roles

Choosing scopes