# Verify Client API Reference for AI Agents

Purpose: help AI agents build against the Verify Client API without inferring behaviour from UI code or product PRDs.

Canonical API docs:
- docs/api/ai-build-reference.md
- docs/api/api-integrations.openapi.yaml

Public API docs:
- /integrations/developer-docs
- /integrations/developer-docs/llms.txt
- /integrations/developer-docs/api-integrations.openapi.yaml

Implementation source of truth:
- api/routes/v1/microapps.ts
- api/routes/v1/cases.ts
- api/auth/auth.ts
- api/auth/types.ts
- api/microapps/microappScopes.ts
- api/microapps/sourceRestrictions.ts
- shared/microapps.ts
- shared/access-control.ts

Current supported AI-build use case:
- A firm admin creates an `api_integration` in Firm -> Apps & API access.
- The external system exchanges `clientId` + one-time `clientSecret` for a scoped bearer token.
- The external system can create an onboarding case, add parties, and send invites when the token has the required scopes.

Recommended AI crawl order:
1. Read this file.
2. Read docs/api/ai-build-reference.md or /integrations/developer-docs.
3. Load docs/api/api-integrations.openapi.yaml or /integrations/developer-docs/api-integrations.openapi.yaml for schemas.
4. Inspect implementation source files only if a required endpoint or field is missing from the docs.

Base URLs:
- Browser/frontend local proxy: /api/v1
- Local API direct: http://localhost:8081/v1
- Production API is routed behind the deployed frontend domain; prefer relative /api/v1 from browser contexts.

Auth summary:
- Portal users use Cognito bearer tokens.
- API integrations use POST /v1/microapps/system-tokens with client credentials.
- Do not open /api/v1/microapps/system-tokens as a browser URL. It must be called as POST with JSON from server-side code.
- Integration calls use Authorization: Bearer <accessToken>.
- Only `tokenKind=system` MicroApp tokens can call first-party automation endpoints.

Important constraints:
- Never store or expose `clientSecret` after creation; it is returned once.
- Use the least scopes required.
- Respect `allowedIpRanges` when configured.
- Treat `caseId`, `partyId`, and `inviteId` as opaque strings.
- Do not invent undocumented endpoints. If an endpoint is not in docs/api or api/routes/v1, inspect implementation before using it.
- Generate backend/server code for client credentials. Never generate browser code that contains `clientSecret`.
- Branch on HTTP status first. Treat `error.message` and `error.code` as optional.

Scopes:
- cases.create: POST /v1/cases
- parties.manage: POST /v1/cases/{caseId}/parties
- invites.send: POST /v1/cases/{caseId}/invites
- cases.read: reserved for read endpoints as exposed
- cases.list: reserved for list endpoints as exposed
- cases.ids.list: GET /v1/microapps/api/cases/ids
- users.list: GET /v1/microapps/api/users

Endpoint contracts:
- POST /v1/microapps/system-tokens -> request clientId, clientSecret, optional scopes, optional expiresInSeconds; response accessToken, principal, expiresAt.
- GET /v1/microapps/api/cases/ids -> requires cases.ids.list; request optional limit and cursor; response opaque case IDs and nextCursor for ledger sync/connectivity checks.
- POST /v1/cases -> requires cases.create; request matterRef, matterType, optional propertyAddress, requireSof, demoMode, expiresAt, fees, parties; response caseId, status, parties.
- POST /v1/cases/{caseId}/parties -> requires parties.manage; request party fields with required name; response created party.
- POST /v1/cases/{caseId}/invites -> requires invites.send; request partyId and optional channel/message fields; response invite metadata.

Duplicate safeguards:
- Use a stable source-system matterRef. POST /v1/cases rejects duplicate matterRef values within the firm.
- Use GET /v1/microapps/api/cases/ids only as a scoped case-ID sync/connectivity endpoint, not as full-text search.
- 401 means credentials/token are missing, expired, malformed, or invalid; refresh/rotate credentials and do not treat it as duplicate uncertainty.
- 403 means valid credentials lack scope, active integration status, or allowed source IP/origin configuration.
- 5xx or network timeout means remote state is unknown. Block live creation unless an operator explicitly accepts local-ledger-only dedupe for that run.