Documentation

Open Badges

2.0 and 3.0, the URLs, baked images, and what resolves when.

Every published credential is available as Open Badges 2.0 and Open Badges 3.0 / W3C Verifiable Credential. Public, no key, CORS open to any origin — a badge consumer is a page on somebody else's domain by definition.

We say conformant, never certified. Certification requires a 1EdTech listing, and until that exists the word would be false.

The URLs

{key} is the credential's id.

URL Returns
/v1/openbadge/{key}/badge.json 2.0 Assertion, hosted verification
/v1/openbadge/{key}/badgeclass.json 2.0 BadgeClass
/v1/openbadge/{key}/issuer.json 2.0 Issuer profile
/v1/openbadge/{key}/badge.png PNG with the assertion URL baked in
/openbadge/v3/{key}/credential.json 3.0 credential, signed
/openbadge/v3/{key} The same, unsigned
/openbadge/v3/{key}/achievement.json The achievement alone
/openbadge/v3/{key}/revocation_list.json 1EdTechRevocationList
/openbadge/v3/{key}/badge.png PNG with the whole signed credential baked in
/openbadge/v3/issuers/{id}/did.json The issuer's DID document

An unrecognised filename redirects rather than 404ing. Consumers in the wild guess assertion.json; a 404 reads to them as "this badge is fake".

What "baked" means

A badge image is not a picture of a credential — it carries the credential inside the file. 2.0 writes the assertion's address into a metadata chunk named openbadges; 3.0 writes the entire signed credential into one named openbadgecredential. That is what lets any badge-aware software read a badge it has never seen before, from a file somebody emailed.

If a tool says an image carries no badge data, it is almost always a screenshot — a picture of a badge rather than a badge.

Signing

3.0 credentials are signed with eddsa-rdfc-2022 under the issuer's own did:web, derived from the API host. The DID document publishes every key that has not been revoked, so a credential signed two years ago still verifies after a rotation.

Signed once, at publish, and stored. The same bytes come back on every request, so the document can be cached and content-addressed, and the baked image carries exactly what the endpoint serves.

Revocation

State 2.0 badge.json 3.0 revocation list
Valid 200, the assertion revoked: false
Revoked 410 Gone, revoked: true revoked: true
Suspended 410 Gone, revoked: true revoked: true

Open Badges has no "suspended", so suspension maps to revoked and reverses on unsuspend. The reason string is what tells a reader which it was. Everything else — the badge class, the issuer, the 3.0 document, the images — keeps answering, because a consumer must be able to read "withdrawn" rather than "missing".

Recipient identity

  • 2.0: sha256$ of the email followed by a salt, with the salt published in the assertion. Salted so the same address does not produce the same hash on every platform, which would make it a cross-platform tracking key.
  • 3.0: sha256$ of the email, unsalted. The specification changed its mind, and a verifier hashing the address they hold has to get the same answer we did.