Authentication
Every authenticated request carries an API key in the x-api-key header:
curl -s "https://api.warrants.ecourtdate.com/v1/warrants" \
-H "x-api-key: $API_KEY"
A request with no key is rejected with 401 missing_api_key; a key that is
invalid, expired, or revoked is rejected with 401 invalid_api_key
(error registry).
The endpoints under public links are the only exception: they take no key at all.
Keys are agency-scoped
A key belongs to exactly one agency, and every call it makes reads and writes inside that agency. There is no header to switch agencies and no way to reach another agency's records with your key. An integration that serves several agencies holds one key per agency.
Getting and managing keys
Keys are issued and activated for your agency by eCourtDate. Ask your eCourtDate contact for a key, tell them which scopes the integration needs, and treat the result like a password:
- Store it in a secrets manager, never in source control or client-side code.
- Use a separate key per integration, so each can be rotated or revoked on its own and shows up distinctly in the audit trail.
- Grant the narrowest scopes that let the integration do its job.
- Rotate on a schedule and immediately on suspected exposure: take the replacement key, deploy it, then have the old one revoked.
Scopes
Each key carries scopes that gate what it may call. The reference lists the required scope on every operation.
| Scope | Grants |
|---|---|
warrants:read | Read applications, comments, lock state, and the assignable judges |
warrants:write | Create and update applications, comment, lock, assign, set priority and visibility, trash and restore |
warrants:submit | Submit a draft for review |
warrants:sign | Sign or reject a submitted application |
templates:read | Read templates and document styles |
templates:write | Create, update, duplicate, and delete templates |
files:read | List and download attachments |
files:write | Upload, confirm, and delete attachments |
locations:read | Read locations |
locations:write | Create, update, and delete locations |
users:read | Read users, roles, and the permission catalog |
users:write | Add and update users, manage custom roles |
settings:read | Read agency settings |
settings:write | Change agency settings |
audit:read | Read the audit trail |
Calling an operation the key's scopes do not cover returns 403
insufficient_scope.
Signing is deliberately its own scope. A key that files applications all day
does not need to be able to sign one, and most integrations should not hold
warrants:sign at all.
Actor attribution: X-On-Behalf-Of
Every write also requires an X-On-Behalf-Of header naming the person the call
is made for, as an email address or a user id (1 to 128 printable characters):
curl -s -X PATCH "https://api.warrants.ecourtdate.com/v1/warrants/$WARRANT_ID/submit" \
-H "x-api-key: $API_KEY" \
-H "X-On-Behalf-Of: dr.chen@example.gov"
A warrant application is a legal record. The audit trail has to show which
person applied, reviewed, or signed, not merely which system made the call, so
a write without the header fails with 422 missing_actor, and a header
naming somebody who is not a member of the agency fails with 403
unknown_actor.
The named person must also be entitled to the action. Attribution is not a way around permissions: submitting attributes to the applicant and requires that they created the draft, and signing attributes to a judge and requires that they may sign.
Signing on someone's behalf
Signing is the one action where attribution has legal weight. The signature
applied to the document is the stored signature of the person named in
X-On-Behalf-Of, and both the signature and the signer are recorded on the
warrant. An integration cannot sign as itself, and it cannot sign for a person
who does not hold signing rights in that agency.
Reading a key's own identity
There is no "current user" endpoint for API keys, because a key is not a person. To discover who exists in the agency, list users or the assignable judges.