Skip to content
emergent engineering

Per-organization issuer profiles with platform-custodial keys

Status: accepted

The first CLR 2.0 / Open Badges 3.0 export we ever produce must be signed, so the issuer model precedes everything else in the credential lane (ADR-0013 staged learner keys; this ADR covers issuer keys, which are needed first and are entirely server-side).

Decision

Section titled “Decision”
  • Issuers are per-organization Profiles from the start. Each issuing Organization is a CLR/OB issuer Profile; the platform itself is simply the default issuer Profile, used for independent learners’ achievements. qualification_award. issuer_organization_id already encodes this intent.
  • Keys are platform-custodial in a KMS. Organizations (schools, tutors) never hold or manage signing keys.
  • Issuer identifiers are HTTPS URIs with JWKS endpoints first; did:web is added later as an additive alias if wallet ecosystems demand it. Unlike credential subjects, an issuer dying with its domain is semantically correct — an issuer genuinely is an institution at a domain.
  • Evidence by reference only. Signed credentials embed the minimum personal data: achievement claims plus provenance references (e.g. statement ids), never xAPI statement excerpts or response content. A signed document is un-erasable by construction (ADR-0014), so PII must not be frozen into it. This resolves open decision #2 in docs/integration/lrs-clr-record-mapping.md.
  • Issuer provenance survives org archival. The set null on qualification_award.issuer_organization_id is replaced with a preserved reference, consistent with the no-destruction lifecycle (orgs archive, never delete).

Considered and rejected

Section titled “Considered and rejected”
  • Platform-only single issuer. Cheaper now, but credentials reading “issued by Emergent” instead of by the school mean less to verifiers, and retrofitting issuer granularity after credentials are in the wild means re-issuance debt.
  • Org-held signing keys. Operationally unrealistic for schools and tutors; recreates the key-custody problem at the least capable layer.
  • did:key issuers. No rotation; key compromise would mean issuer identity loss.
  • Embedding xAPI excerpts as credential evidence. Freezes personal data in un-erasable signed documents; conflicts directly with ADR-0014.

Consequences

Section titled “Consequences”
  • New issuer-profile model keyed to Organization (platform default profile included), KMS-held keys, key-rotation policy, and a public JWKS endpoint in apps/api.
  • The CLR/OB export assembler builds on @conform-ed/contracts (clr/v2_0, open-badges/v3_0) with pairwise subject identifiers minted as identity bindings (ADR-0013).
  • Sign-on-export remains the issuance architecture (no stored signed artifacts); credentialStatus/revocation infrastructure is deferred but identifier slots are reserved at issuance.