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.