Developers
API reference
Generated from the contract this application serves, not written alongside it.
The contract publishes 68 operations. They are listed below in 6 groups. The machine-readable contract is at /developers/openapi.json, and a typed client is generated from the same document. Group names, paths and parameter names appear exactly as the contract writes them. None of the reference below is maintained by hand, so it cannot fall behind the API.
There is no API credential you can hold yet.
The contract declares experienceSession (apiKey in cookie). A cookie is issued by an interactive sign-in and belongs to a browser, so there is no credential you could hold and present. Issuing, listing and revoking a machine credential is not built. The operations that do not need a session are not a way in either: they take a signature or a token this deployment issues, and they are named below. Read this reference as the shape of the API, not as an invitation to integrate against it today.
Authorization is not visible in this contract.
61 of 68 operations attach no security requirement in the document at all. That is a gap in the published contract rather than a statement about the handlers, but it is not one gap with one answer behind it. What each of those operations actually requires is set out below, class by class, and the classes are not interchangeable: 51 by browser session and a permission check, 6 by provider signature, 1 by a bootstrap token in the body, and 3 by nothing at all. Check the class before you decide what an operation needs.
How each operation is authenticated
Derived from the contract and checked against the handlers. What stood here before was one hand-written sentence, and it was false for ten of these operations.
| What the caller presents | Operations | What the handler does with it |
|---|---|---|
| Browser session, plus a permission and an account scope | 51 | The handler calls requirePermission with a named permission and the account it is acting inside, which rejects an unauthenticated request with 401 and an out-of-scope one with 403. There is no credential a caller outside a browser can present for these today. |
| Provider signature over the raw request body | 6 | No session, no permission and no account scope. The signature is the whole control: it is verified against the unparsed body, and the event id is claimed so a redelivery is deduplicated rather than applied twice. These routes are deliberately exempt from the CSRF and idempotency-key checks, and the browser proxy does not put sign-in in front of them. |
| A bootstrap token carried in the request body | 1 | The caller has no account yet, so there is nothing to scope to and no permission to resolve. A server-issued registration token is verified against the registrant's email and business domain. Apart from the webhook namespace, which bypasses sign-in entirely, this is the only API path the browser proxy serves to a caller with no session. |
| Nothing | 3 | The handler authenticates nobody and authorizes nothing. These report whether their API lane's dependencies are configured, and return no account data. The browser proxy still requires a session to reach them, so they are not anonymous on a deployed origin, but do not read them as authorized, because the handler makes no check. |
| Declared in the contract | 7 | The operation carries a security requirement in the document, so a generated client knows what to present without reading this page. |
The classes below are small enough to name in full, so read them as the exceptions rather than as examples. An operation that is not in one of these lists and does not declare a scheme in the contract is in the browser-session row above.
- Provider signature over the raw request body
- POST/v1/webhooks/esign
- POST/v1/webhooks/marketplaces/{provider}
- POST/v1/webhooks/provisioning
- POST/v1/webhooks/stripe
- POST/v1/webhooks/support/{provider}
- POST/v1/webhooks/workos
- A bootstrap token carried in the request body
- POST/v1/lifecycle/registrations
- Nothing
- GET/v1/core/status
- GET/v1/lifecycle/status
- GET/v1/system/status
core
17 operations
| Operation | Tags | Required parameters | Request body | Responses |
|---|---|---|---|---|
| GET/v1/core/artifacts/{kind}/{id} | core, documents | kind (path), id (path) | No body | 200, 403, 404, 503 |
| POST/v1/core/commands/{resource} | core | resource (path), idempotency-key (header) | Required: application/json | 200, 403, 404, 409 |
| GET/v1/core/payg-offers | core, pricing | None | No body | 200, 403, 503 |
| POST/v1/core/payg-offers | core, pricing | None | Required: application/json | 200, 403, 409, 503 |
| GET/v1/core/payg-offers/billing-effects | core, billing | None | No body | 200, 403, 503 |
| POST/v1/core/payg-offers/billing-effects | core, billing | None | Required: application/json | 200, 403, 409, 503 |
| GET/v1/core/payg-offers/enrollments | core, billing | None | No body | 200, 403, 503 |
| POST/v1/core/payg-offers/enrollments | core, billing | None | Required: application/json | 200, 403, 409, 503 |
| POST/v1/core/payg-offers/simulate | core, pricing | None | Required: application/json | 200, 403 |
| GET/v1/core/payg-offers/trials | core, trials | None | No body | 200, 403, 503 |
| POST/v1/core/payg-offers/trials | core, trials | None | Required: application/json | 200, 403, 409, 503 |
| POST/v1/core/payment-sessions | core, billing | idempotency-key (header) | Required: application/json | 200, 403, 409, 503 |
| GET/v1/core/records/{resource} | core | resource (path) | No body | 200, 403 |
| POST/v1/core/replays/{provider}/{eventId} | core, operations | provider (path), eventId (path) | Required: application/json | 200, 403 |
| GET/v1/core/reports/{report} | core, reports | report (path) | No body | 200, 403 |
| GET/v1/core/status | core | None | No body | 200 |
| POST/v1/webhooks/stripe | core, webhooks | stripe-signature (header) | Required: application/json | 200, 503 |
Experience artifacts
3 operations
| Operation | Tags | Required parameters | Request body | Responses |
|---|---|---|---|---|
| GET/api/experience/artifacts/{kind}/{artifactId} | Experience artifacts | kind (path), artifactId (path) | No body | 200, 403, 404, 409, 422, 502, 503 |
| POST/api/experience/artifacts/render-requests | Experience artifacts | x-csrf-token (header), idempotency-key (header) | Required: application/json | 201, 403, 409, 422, 503 |
| POST/api/experience/artifacts/render-requests/{requestId} | Experience artifacts | x-csrf-token (header), idempotency-key (header), requestId (path) | No body | 201, 403, 404, 409, 422, 502, 503 |
Experience projections
4 operations
| Operation | Tags | Required parameters | Request body | Responses |
|---|---|---|---|---|
| GET/api/experience/projections/{audience}/{channel} | Experience projections | audience (path), channel (path) | No body | 200, 403, 422, 503 |
| GET/api/experience/projections/{audience}/{channel}/{recordKey} | Experience projections | audience (path), channel (path), recordKey (path) | No body | 200, 403, 404, 503 |
| POST/api/experience/projections/{audience}/{channel}/{recordKey}/actions | Experience projections | x-csrf-token (header), idempotency-key (header), audience (path), channel (path), recordKey (path) | Required: application/json | 202, 403, 404, 409, 422, 503 |
| GET/api/experience/projections/{audience}/{channel}/{recordKey}/actions/{actionRequestId} | Experience projections | audience (path), channel (path), recordKey (path), actionRequestId (path) | No body | 200, 403, 404, 503 |
lifecycle
32 operations
| Operation | Tags | Required parameters | Request body | Responses |
|---|---|---|---|---|
| POST/v1/lifecycle/account-selection | lifecycle, identity | idempotency-key (header) | Required: application/json | 200, 403, 503 |
| PUT/v1/lifecycle/accounts/{accountId}/procurement-profile | lifecycle, onboarding | accountId (path), idempotency-key (header) | Required: application/json | 200, 403, 503 |
| GET/v1/lifecycle/accounts/{accountId}/support-signals | lifecycle, support | accountId (path) | No body | 200, 403, 503 |
| POST/v1/lifecycle/agreement-templates | lifecycle, agreements | idempotency-key (header) | Required: application/json | 200, 403, 503 |
| GET/v1/lifecycle/agreement-templates/active | lifecycle, agreements | type (query), jurisdiction (query) | No body | 200, 403, 404, 503 |
| POST/v1/lifecycle/agreements/click-through | lifecycle, agreements | idempotency-key (header) | Required: application/json | 200, 403, 503 |
| POST/v1/lifecycle/agreements/customer-paper | lifecycle, agreements | idempotency-key (header) | Required: application/json | 200, 403, 503 |
| POST/v1/lifecycle/agreements/envelopes | lifecycle, agreements | idempotency-key (header) | Required: application/json | 200, 403, 503 |
| POST/v1/lifecycle/end-user-terms/acceptances | lifecycle, agreements | idempotency-key (header) | Required: application/json | 200, 403, 503 |
| POST/v1/lifecycle/exceptions | lifecycle, exceptions | idempotency-key (header) | Required: application/json | 200, 403, 503 |
| POST/v1/lifecycle/exceptions/{caseId}/decisions | lifecycle, exceptions | caseId (path), idempotency-key (header) | Required: application/json | 200, 403, 503 |
| POST/v1/lifecycle/migrations | lifecycle, migrations | idempotency-key (header) | Required: application/json | 200, 403, 503 |
| POST/v1/lifecycle/migrations/{runId}/matches/{legacyAccountId}/decision | lifecycle, migrations, exceptions | runId (path), legacyAccountId (path), idempotency-key (header) | Required: application/json | 200, 403, 503 |
| POST/v1/lifecycle/notices | lifecycle, renewals | idempotency-key (header) | Required: application/json | 200, 403, 503 |
| POST/v1/lifecycle/novations | lifecycle, offboarding | idempotency-key (header) | Required: application/json | 200, 403, 503 |
| POST/v1/lifecycle/organizations/{organizationId}/invites | lifecycle, identity | organizationId (path), idempotency-key (header) | Required: application/json | 200, 403, 503 |
| POST/v1/lifecycle/partners/{accountId}/domains | lifecycle, identity, partners | accountId (path), idempotency-key (header) | Required: application/json | 200, 403, 503 |
| POST/v1/lifecycle/pocs | lifecycle, pocs | idempotency-key (header) | Required: application/json | 200, 403, 503 |
| POST/v1/lifecycle/pocs/{pocId}/conversion | lifecycle, pocs | pocId (path), idempotency-key (header) | Required: application/json | 200, 403, 503 |
| POST/v1/lifecycle/pocs/{pocId}/decisions | lifecycle, pocs, exceptions | pocId (path), idempotency-key (header) | Required: application/json | 200, 403, 503 |
| POST/v1/lifecycle/provisioning/{commandId}/recover | lifecycle, provisioning | commandId (path), idempotency-key (header) | Required: application/json | 200, 403, 503 |
| POST/v1/lifecycle/registrations | lifecycle, onboarding | idempotency-key (header) | Required: application/json | 200, 403, 503 |
| GET/v1/lifecycle/renewals | lifecycle, renewals | None | No body | 200, 403, 503 |
| POST/v1/lifecycle/renewals/{orderId}/declines | lifecycle, renewals | orderId (path), idempotency-key (header) | Required: application/json | 200, 403, 503 |
| POST/v1/lifecycle/renewals/{orderId}/requests | lifecycle, renewals | orderId (path), idempotency-key (header) | Required: application/json | 200, 403, 503 |
| GET/v1/lifecycle/status | lifecycle | None | No body | 200 |
| POST/v1/lifecycle/terminations | lifecycle, offboarding | idempotency-key (header) | Required: application/json | 200, 403, 503 |
| POST/v1/lifecycle/terminations/{terminationId}/approvals | lifecycle, offboarding | terminationId (path), idempotency-key (header) | Required: application/json | 200, 403, 503 |
| POST/v1/webhooks/esign | lifecycle, webhooks | esign-signature (header) | Required: application/json | 200, 503 |
| POST/v1/webhooks/marketplaces/{provider} | lifecycle, webhooks, marketplaces | provider (path), marketplace-signature (header) | Required: application/json | 200, 503 |
| POST/v1/webhooks/provisioning | lifecycle, webhooks, provisioning | provisioning-signature (header) | Required: application/json | 200, 503 |
| POST/v1/webhooks/support/{provider} | lifecycle, webhooks, support | provider (path), support-signature (header) | Required: application/json | 200, 422, 503 |
notifications
3 operations
| Operation | Tags | Required parameters | Request body | Responses |
|---|---|---|---|---|
| GET/v1/notifications | notifications | accountId (query) | No body | 200, 403, 503 |
| GET/v1/notifications/preferences | notifications | accountId (query) | No body | 200, 403, 503 |
| PUT/v1/notifications/preferences | notifications | idempotency-key (header) | Required: application/json | 200, 403, 422, 503 |
system
9 operations
| Operation | Tags | Required parameters | Request body | Responses |
|---|---|---|---|---|
| POST/v1/system/exception-cases/{caseId}/reassign | system, operations | caseId (path), idempotency-key (header) | Required: application/json | 200, 403, 404, 409, 422, 503 |
| PUT/v1/system/exception-roster/{rosterEntryId} | system, operations | rosterEntryId (path), idempotency-key (header) | Required: application/json | 200, 201, 403, 409, 422, 503 |
| GET/v1/system/external-gates | system, operations | None | No body | 200, 403, 503 |
| PUT/v1/system/external-gates/{gateKey} | system, operations | gateKey (path), idempotency-key (header) | Required: application/json | 200, 403, 404, 409, 422, 503 |
| POST/v1/system/external-gates/{gateKey}/activation-tasks | system, operations | gateKey (path), idempotency-key (header) | Required: application/json | 202, 403, 404, 409, 503 |
| POST/v1/system/external-gates/{gateKey}/activation-tests | system, operations | gateKey (path), idempotency-key (header) | Required: application/json | 200, 403, 404, 409, 503 |
| PUT/v1/system/external-gates/{gateKey}/emergency-state | system, operations | gateKey (path), idempotency-key (header) | Required: application/json | 200, 403, 404, 409, 422, 503 |
| GET/v1/system/status | system | None | No body | 200 |
| POST/v1/webhooks/workos | system, webhooks | workos-signature (header) | Required: application/json | 200, 503 |
What is missing before you can integrate
Stated here rather than discovered after a contract is signed.
- Not built Credential management. There is no way to issue, list or revoke a key scoped to an account, and no audit trail for one, because there is no store to hold a key hash in.
- Not built A sandbox. No environment exists that a caller can exercise these operations against without touching real commercial records.
- Partial Security in the contract. 7 of 68 operations declare a scheme; the rest declare none, and what they require has to be read from the table above rather than from the document. Until the contract carries it, a generated client cannot present a credential automatically and cannot tell those classes apart.
Rendered from the contract at build time. If an operation is listed here, the application serves it; if the application stops serving it, this page loses it on the next build.