Skip to main content

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​

The integration contract in three stepsYour platform mints a signed launch token. The browser form-posts it to Pollinator, which verifies it against your published keys and redirects the person into the activity. Pollinator later sends a signed outcome event to your webhook, or you pull it.Your platformPollinator1. Mint a signedlaunch token (JWT)2. Browser form-POSTs itVerify with your JWKS,burn the jti303 into the activity(participant answers in Pollinator)3. Signed outcome event(webhook, or pulled with an API key)
Launch in, outcomes back. The launch is verified asymmetrically with your public keys; outcomes are signed with a secret Pollinator issued to you.

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​

PageWhat it covers
Registration and linkingRegistering your platform in a workspace, and linking your resources to Pollinator activities.
The launchThe launch token, its claims, the launch endpoint, the exchange step and framing.
Outcome eventssubmission.completed and session.closed, their payloads, and the privacy rules that decide whether they exist.
Webhook signatures and deliveryVerifying X-Pollinator-Signature, retries and idempotency.
Pulling outcomesReading the same events with an API key and an opaque cursor, instead of or as well as webhooks.
Self-service registrationRegistering your platform yourself with a registration key, for an admin to approve.
Errors and versioningEvery 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:

  1. An RSA or EC key pair, and an HTTPS endpoint serving the public key as a JSON Web Key Set.
  2. A server-side function that mints a launch token per launch.
  3. A self-submitting HTML form that posts the token to Pollinator.
  4. If you want outcomes: a webhook handler that verifies the signature, deduplicates on event_id and returns 2xx - or a job that pulls outcomes.

A workspace owner or admin then registers your issuer and links your resources.