Assertion Records, Status, and Revocation

Assertion URL

A typical assertion URL looks like:

https://example.com/a/BADGE_ID.json

The badge contains this URL in its signed attestation.

The checkmark in the badge also links to the assertion URL.

Exporting an Assertion

In Static Hosting Export:

Select a Status.
Optionally enter Expiry in hours.
Click Download /a/<id>.json.
Publish the downloaded file at the corresponding assertion URL.

Status Values

The interface supports:

Status	Meaning
`active`	The issuer currently presents the badge as active
`revoked`	The issuer has withdrawn the badge's active status

The default is active.

Assertion JSON Fields

Field	Description
`v`	Format version
`id`	Badge identifier
`img_sha256`	Badge artwork hash
`kid`	Signing key identifier
`iat`	Original badge issue timestamp
`status`	Active or revoked
`updated`	Assertion generation time
`exp`	Optional Unix expiration timestamp
`url`	Assertion URL
`sig`	Assertion signature

Example Assertion

{
  "v": 1,
  "id": "A1B2C3D4E5F6",
  "img_sha256": "sha256:FULL_SHA256_HEX_VALUE",
  "kid": "badge-signing-2026-01",
  "iat": 1792281600,
  "status": "active",
  "updated": "2026-10-18T04:00:00.000Z",
  "exp": "",
  "url": "https://example.com/a/A1B2C3D4E5F6.json",
  "sig": "BASE64URL_SIGNATURE"
}

Values shown are illustrative placeholders.

Assertion Signature

The assertion is signed using the message:

BAR1S|id|img_sha256|status|updated|exp|kid

The signature is generated using the badge's associated signing key.

This is separate from the SVG attestation signature.

Expiration

The Expiry field accepts a number of hours.

If greater than zero, the application calculates:

Current Unix time + expiry hours × 3600

The resulting timestamp is placed in exp.

If the field is zero, exp is an empty string.

Important Verification Limitation

The supplied verify.html implementation does not currently reject an assertion when its expiration timestamp has passed.

The expiry value is exported and signed, but expiration enforcement is not implemented in the supplied verifier.

Do not represent the existing verifier as providing enforced expiration until that check is added.

Revoking a Badge

To publish a revoked status:

Select revoked.
Download a new assertion JSON.
Replace the hosted assertion file at the existing URL.
Verify the published badge again.

The online status check should then report that the assertion is not active.

Does Revocation Modify the SVG?

No.

Revocation is represented in the separately hosted assertion file.

The original SVG can remain unchanged.

Does Revocation Require a Server?

Not necessarily.

BadgeMax Pro supports static hosting.

An administrator can generate and upload a replacement JSON file without running a dedicated signing API.

However, changing a hosted file still requires access to the hosting environment.

What Happens if the Assertion Is Unavailable?

The exported verifier attempts to fetch the assertion URL.

If the request fails, it records an online-check failure.

The supplied verifier treats this as an unsuccessful overall verification.

Important Integrity Limitation

The current exported verifier checks the assertion's status and verifies its signature when a sig field exists.

However, it does not require a signature to be present, and it does not fully cross-check every assertion field against the SVG attestation.

This means the current implementation should not be described as providing complete cryptographically enforced revocation until these checks are strengthened.

Recommended Practices

Publish assertion files over HTTPS.
Use stable assertion URLs.
Preserve signing keys securely.
Sign status updates.
Replace revoked assertion files promptly.
Avoid long-lived caching for status records.
Independently test verification after publication.

Security note: A production verifier should require a valid assertion signature, compare assertion identifiers and hashes against the badge attestation, and enforce expiration where applicable.