API reference
Quick reference for the Partner API v1. For the full walkthrough, start at Getting started.
- Base URL:
https://locke-api.trylockey.workers.dev/partner/v1(read from config — the domain flips totrylockey.comonce cut over). - Auth:
Authorization: Bearer <key>— see Authentication.
Endpoint summary
| Method | Path | Scope | Purpose |
|---|---|---|---|
| GET | /partner/v1/ping | auth only | Credential smoke test |
| POST | /partner/v1/requests | requests:write | Create a document request |
| GET | /partner/v1/requests | requests:read | List requests (filter by status, reference) |
| GET | /partner/v1/requests/:id | requests:read | Fetch one request |
| GET | /partner/v1/grants | grants:read | List grants |
| GET | /partner/v1/grants/:id | grants:read | Fetch one grant |
| POST | /partner/v1/grants/:id/sessions | grants:read | Mint a watermarked viewing session |
Scopes
| Scope | Grants access to |
|---|---|
requests:write | Create document requests |
requests:read | List / fetch requests |
grants:read | List / fetch grants and mint viewing sessions |
webhooks:write | Reserved — not yet implemented (poll instead) |
verify:read | Reserved — not yet implemented |
Not yet available
- Webhooks / callbacks — the
webhooks:writescope is reserved but no delivery exists. Poll the request endpoints instead. - Verification API — the
verify:readscope is reserved; no route yet.
Source of truth
These are the current wire contracts. The authoritative definitions live in the Locke monorepo:
- Machine API route:
apps/api/src/routes/partner/v1.ts - Validation schemas:
packages/validation - API contracts:
packages/contracts
Going live requires org verification — see the partner approval runbook in the repo (docs/runbooks/partner-approval.md).