Ephemeral Everything you create here is tied to a key in your browser's session storage and is purged 24 hours after creation. Do not enter real student data.
Menu

Build guide

Implement an SDI provider

A conformant Provider needs four things. Build them incrementally; the harness verifies each. Section references (§) point into the SDI standard.

§1

Publish your discovery document

Serve JSON at GET {base}/.well-known/sdi-configuration, unauthenticated. It advertises your endpoints, supported OAuth grants, scopes, capabilities, and languages. The harness validates every required field.

§2

Implement OAuth 2.0

You are the authorization server. Support at least one grant:

  • Client Credentials — an admin provisions a client and pastes client_id/client_secret into Admissio.
  • Authorization Code + PKCE (recommended) — one-click consent, no secret to copy. Pair it with Dynamic Client Registration, but gate registration with a signed software statement or an initial access token (§6.1.2).

Keep access tokens short-lived; rotate refresh tokens with reuse detection (§6.3). Reject calls whose token lacks the required scope with 403.

§3

Publish your field schema + ingest

Return a Draft 2020-12 JSON Schema of the fields you expect (use SDI canonical names — givenName, email, programme — where they fit). Annotate every field with a title; it powers Admissio's mapping UI.

Your ingest endpoint returns one result per record. The harness checks:

  • Validate each record; reject the bad one with field problems but never fail the whole batch.
  • Be idempotent on Idempotency-Key + recordRef; upsert by recordRef; return your id as externalId.
§4

Resolve documents — only if you accept them

Documents transfer by reference. Each descriptor carries an id and a resolveUrl. To get the bytes, you call Admissio with a signed JWT assertion (private_key_jwt) whose aud is the resolveUrl, signed with the key at your jwks_uri. Admissio returns a short-lived signed URL; download it and verify the sha256 before storing.

§—

Libraries

The provider guide builds on these. None are required — pick what fits your stack, whether you run on Node.js or an edge platform.

  • OAuth server — oidc-provider (a full authorization server that mounts in Express) or @node-oauth/oauth2-server (a minimal, framework-agnostic core — you add discovery and JWKS yourself).
  • JWT & JWKS — jose for signing and verifying assertions, software statements, and tokens.
  • Schema validation — Ajv with ajv-formats (Draft 2020-12), the lighter @cfworker/json-schema, or Zod if you already validate with it.

Full normative text: the SDI standard · provider guide at sdi.admissio.app.