The integration contract, v1
Contract version: 1 · Status: published
This is how an external platform - a learning management system, a course site, an intranet - sends people into Pollinator activities and learns how they did. It is written for an engineer on that platform. Pollinator does not know or care which product is on the other end: every integration speaks this one contract, and Pollinator never calls a product-specific API on yours.
In these pages {POLLINATOR} is the public origin of the Pollinator deployment you integrate
with, for example https://pollinator.example.org, with no trailing slash. MUST, SHOULD and MAY
are used in their RFC 2119 sense.
The shape of an integration
Two trust mechanisms, one per direction:
- Inbound (launch) is asymmetric. You sign with your private key; Pollinator verifies with the public keys you publish. Pollinator never holds anything that could mint one of your users.
- Outbound (outcomes) is symmetric. Pollinator signs each webhook with a secret it issued to you once, at registration.
Pollinator is the system of record for questions, responses and analytics. You store what your own model needs - typically a completion and a score - and nothing more.
The parts of the contract
| Page | What it covers |
|---|---|
| Registration and linking | Registering your platform in a workspace, and linking your resources to Pollinator activities. |
| The launch | The launch token, its claims, the launch endpoint, the exchange step and framing. |
| Outcome events | submission.completed and session.closed, their payloads, and the privacy rules that decide whether they exist. |
| Webhook signatures and delivery | Verifying X-Pollinator-Signature, retries and idempotency. |
| Pulling outcomes | Reading the same events with an API key and an opaque cursor, instead of or as well as webhooks. |
| Self-service registration | Registering your platform yourself with a registration key, for an admin to approve. |
| Errors and versioning | Every launch error message, and the rules for how the contract changes. |
Conforming clients
A conforming client mints launch tokens as described, accepts or pulls outcome events, and verifies their signatures. Nothing else is required of it, and Pollinator treats every conforming client identically. Pamba was the first, and is documented as a worked example.
Writing a new client
The minimum:
- An RSA or EC key pair, and an HTTPS endpoint serving the public key as a JSON Web Key Set.
- A server-side function that mints a launch token per launch.
- A self-submitting HTML form that posts the token to Pollinator.
- If you want outcomes: a webhook handler that verifies the signature, deduplicates on
event_idand returns2xx- or a job that pulls outcomes.
A workspace owner or admin then registers your issuer and links your resources.