Verifying an Open Badge Signature in Node.js, Python, and Go

Three working code samples (Node, Python, Go) for fetching a signed Open Badge credential, resolving the issuer's public key, and verifying the JWS signature.

Nacho Coll By Updated 10 min read
Three working code samples (Node, Python, Go) for fetching a signed Open Badge credential, resolving the issuer's public key, and verifying the JWS signature.

If you issue credentials, most of the verification work happens without you: a recipient shares a link, an employer clicks it, and the verification page does the rest. But sooner or later someone asks a sharper question. “How do I know this file was really signed by you, and not edited after the fact?” That question is answered by a digital signature, and checking one takes about fifteen lines of code in any mainstream language.

This tutorial shows how to verify a signed Open Badges 3.0 credential issued through https://badges.ninja, step by step, in Node.js, Python, and Go. You do not need to run any of it to issue credentials. It is for the people who want to audit the system, build an internal verification tool, or simply understand what “verifiable” means in practice.

What you are actually verifying

There are two layers of verification in Open Badges, and it helps to keep them apart.

Hosted verification is the Open Badges 2.0 model. The award has a public URL, and anyone who opens it sees the issuer, the badge, the recipient’s hashed identity, and the status. Trust comes from the fact that the data is served from the issuer’s own domain. If you can reach the page on https://badges.ninja, the credential is real. This needs no code and no signature.

Signature verification is the Open Badges 3.0 model, built on W3C Verifiable Credentials. The credential is packaged as a signed token, so it can be checked offline, years later, even if it was copied into a wallet or an email attachment. Trust comes from mathematics: the token carries a signature that only the holder of the issuer’s private key could have produced.

On https://badges.ninja, every award is available in both forms. This article is about the second one. If you want the background on how the two versions differ, read Open Badges v2 vs v3, and for a tour of the hosted JSON, see the Open Badge JSON-LD walkthrough.

The moving parts

The signed credential is a VC-JWT: a compact JWS, which is three base64url strings separated by dots.

header.payload.signature
  • The header says how it was signed. For our credentials it contains alg: EdDSA, typ: JWT, and a kid (key id) that looks like did:web:api.badges.ninja#<thumbprint>.
  • The payload holds the claims, including iss (the issuer DID did:web:api.badges.ninja), jti (the credential id), nbf (valid from), an optional exp (expiry), and a vc object with the actual OpenBadgeCredential.
  • The signature is an Ed25519 signature over the exact bytes of header.payload.

The public key that checks the signature is published by the issuer in two places, both without authentication:

  • https://api.badges.ninja/.well-known/jwks.json returns a JWK Set.
  • https://api.badges.ninja/.well-known/did.json returns the DID document for did:web:api.badges.ninja.

The JWKS kid is the RFC 7638 thumbprint of the key. The kid in the token header is the DID URL, and its fragment (the part after #) is that same thumbprint. That fragment is how you pick the right key.

The verification recipe

Every language follows the same five steps:

  1. Fetch the signed credential from the public endpoint.
  2. Split the token into its three parts.
  3. Read the header, check that alg is exactly EdDSA, and take the thumbprint from kid.
  4. Fetch the JWKS and find the key whose kid matches.
  5. Verify the Ed25519 signature over header.payload with that key.

The credential endpoint is public and takes the award id (the same GUID you see in a verification URL such as https://badges.ninja/awards/<awardId>):

curl https://api.badges.ninja/certify-badge/award/<awardId>/vc

By default this returns the signed VC-JWT as application/jwt. Add ?format=json to get the unsigned credential JSON for reading. The verification reference documents both.

Note that there is no separate “verify this for me” endpoint, and that is deliberate. A server that tells you “yes, valid” asks you to trust the server. The whole point of a signature is that you can check it yourself against a published key.

Node.js

Node’s built-in crypto module supports Ed25519 and JWK import, so you need no dependencies.

import crypto from "node:crypto";
const API = "https://api.badges.ninja";
const awardId = process.argv[2];
// —— 1. fetch the signed credential
const jwt = (await (await fetch(`${API}/certify-badge/award/${awardId}/vc`)).text()).trim();
// —— 2. split into parts
const [h, p, s] = jwt.split(".");
const header = JSON.parse(Buffer.from(h, "base64url").toString());
const payload = JSON.parse(Buffer.from(p, "base64url").toString());
// —— 3. refuse anything but EdDSA
if (header.alg !== "EdDSA") throw new Error(`unexpected alg: ${header.alg}`);
const thumbprint = header.kid.split("#")[1];
// —— 4. resolve the public key
const jwks = await (await fetch(`${API}/.well-known/jwks.json`)).json();
const jwk = jwks.keys.find((k) => k.kid === thumbprint);
if (!jwk) throw new Error("no matching key in JWKS");
const publicKey = crypto.createPublicKey({ key: jwk, format: "jwk" });
// —— 5. verify the signature over "header.payload"
const ok = crypto.verify(null, Buffer.from(`${h}.${p}`), publicKey, Buffer.from(s, "base64url"));
console.log(ok ? "signature valid" : "signature INVALID");
console.log("issuer:", payload.iss, "credential:", payload.jti);

The null algorithm argument is correct: with Ed25519 the key type fixes the algorithm. If you prefer a library, jose does the same job with compactVerify and importJWK, and handles the header checks for you.

Python

The cryptography package gives you Ed25519 directly. Install it with pip install cryptography requests.

import base64, json, sys
import requests
from cryptography.exceptions import InvalidSignature
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
API = "https://api.badges.ninja"
award_id = sys.argv[1]
def b64url(data: str) -> bytes:
    return base64.urlsafe_b64decode(data + "=" * (-len(data) % 4))
# —— 1. fetch the signed credential
jwt = requests.get(f"{API}/certify-badge/award/{award_id}/vc").text.strip()
# —— 2. split into parts
h, p, s = jwt.split(".")
header = json.loads(b64url(h))
payload = json.loads(b64url(p))
# —— 3. refuse anything but EdDSA
if header["alg"] != "EdDSA":
    raise SystemExit(f"unexpected alg: {header['alg']}")
thumbprint = header["kid"].split("#")[1]
# —— 4. resolve the public key
keys = requests.get(f"{API}/.well-known/jwks.json").json()["keys"]
jwk = next((k for k in keys if k["kid"] == thumbprint), None)
if jwk is None:
    raise SystemExit("no matching key in JWKS")
public_key = Ed25519PublicKey.from_public_bytes(b64url(jwk["x"]))
# —— 5. verify the signature over "header.payload"
try:
    public_key.verify(b64url(s), f"{h}.{p}".encode())
    print("signature valid")
except InvalidSignature:
    print("signature INVALID")
print("issuer:", payload["iss"], "credential:", payload["jti"])

Python has no JWK import for Ed25519 in this library, so we decode the x coordinate (the raw 32-byte public key) ourselves. That is all a JWK of type OKP with curve Ed25519 contains.

Go

Go’s standard library covers everything, including crypto/ed25519.

package main
import (
	"crypto/ed25519"
	"encoding/base64"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)
const api = "https://api.badges.ninja"
func get(url string) []byte {
	res, err := http.Get(url)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	b, _ := io.ReadAll(res.Body)
	return b
}
func main() {
	awardID := os.Args[1]
	// —— 1. fetch the signed credential
	jwt := strings.TrimSpace(string(get(api + "/certify-badge/award/" + awardID + "/vc")))
	// —— 2. split into parts
	parts := strings.Split(jwt, ".")
	if len(parts) != 3 {
		panic("not a compact JWS")
	}
	enc := base64.RawURLEncoding
	hb, _ := enc.DecodeString(parts[0])
	var header struct{ Alg, Kid string }
	json.Unmarshal(hb, &header)
	// —— 3. refuse anything but EdDSA
	if header.Alg != "EdDSA" {
		panic("unexpected alg: " + header.Alg)
	}
	thumbprint := strings.Split(header.Kid, "#")[1]
	// —— 4. resolve the public key
	var jwks struct {
		Keys []struct{ Kid, X string } `json:"keys"`
	}
	json.Unmarshal(get(api+"/.well-known/jwks.json"), &jwks)
	var pub ed25519.PublicKey
	for _, k := range jwks.Keys {
		if k.Kid == thumbprint {
			pub, _ = enc.DecodeString(k.X)
		}
	}
	if pub == nil {
		panic("no matching key in JWKS")
	}
	// —— 5. verify the signature over "header.payload"
	sig, _ := enc.DecodeString(parts[2])
	ok := ed25519.Verify(pub, []byte(parts[0]+"."+parts[1]), sig)
	fmt.Println("signature valid:", ok)
}

Run it with go run main.go <awardId>. The error handling is trimmed for readability; in a real tool you would check every decode.

Common errors and how to read them

The key is not found in the JWKS. You compared the full kid from the token header (did:web:api.badges.ninja#abc) with the JWKS kid (abc). Compare only the fragment after #. If the fragment still does not match, the issuer may have rotated keys since the token was minted; fetch the DID document and look at its verificationMethod entries.

Signature invalid on a token you just downloaded. Check that you verified header.payload as the original base64url text, not re-encoded JSON. Re-serialising the JSON changes the bytes and breaks the signature. Also check for a trailing newline on the downloaded token.

Algorithm confusion. The classic JWT attack is a token that claims alg: none or switches to a symmetric algorithm so a verifier is tricked into accepting it. Our samples avoid it by hard-coding the expected algorithm, EdDSA, and refusing everything else. Never let the token choose how it gets verified.

Base64 padding errors. JWS uses base64url without padding. Python needs the padding added back (shown above), and Go needs RawURLEncoding, not URLEncoding.

Valid signature, but is the credential still good? A signature proves authenticity and integrity, not current status. A credential can be correctly signed and still revoked or expired. Check exp in the payload, and check the revocation status described next.

Do not forget revocation

Every Open Badges 3.0 credential from https://badges.ninja carries a credentialStatus entry that follows the W3C Bitstring Status List. It points at a status list credential you can fetch at /certify-badge/status/<listId>. When an issuer revokes an award, a bit flips in that list; the list is cached for about a minute, so revocations reach verifiers quickly. Decode the list and read the bit at the credential’s statusListIndex: 1 means revoked, 0 means active. The verification reference includes a short Node example of that bit check.

A complete verifier does three things: verify the signature, check the expiry, and check the revocation bit. If you want to see what revocation looks like from the issuer’s side, the dashboard action is covered in the awards guide.

When you do not need any of this

Most program owners will never write this code, and that is fine. For day-to-day checks, open the award’s public page at https://badges.ninja/awards/<awardId> and read it. The page needs no signup and no key, and it shows the issuer, badge, and status. Recipients can also download the Verifiable Credential from the Download menu on their public credential page, and import it into any Open Badges 3.0 wallet.

Signature checking becomes valuable when:

  • an employer or university wants to automate checks on credentials they receive;
  • you are building a records system that stores copies of credentials and needs to prove they were not altered;
  • an auditor asks for evidence that your credentials are independently verifiable, not just “trust our website”.

The same API key setup used for issuing is not needed here, because all of these endpoints are public. If you do want to issue credentials from code, the API quickstart walks through creating a key and your first award.

API Keys — empty state

Quick reference

ItemValue
Signed credentialGET https://api.badges.ninja/certify-badge/award/<awardId>/vc
Unsigned JSON for readingsame URL with ?format=json
Issuer DIDdid:web:api.badges.ninja
Public keys/.well-known/jwks.json and /.well-known/did.json
AlgorithmEd25519 (EdDSA)
Key matchfragment of header kid equals JWKS kid
RevocationcredentialStatus pointing to /certify-badge/status/<listId>

Wrapping up

Verifying an Open Badge signature is a short, mechanical routine: fetch the token, pin the algorithm, find the key by thumbprint, and check the Ed25519 signature over the first two segments. Add expiry and revocation checks and you have a verifier that trusts nobody but the issuer’s published key. That independence is exactly what makes a digital credential worth more than a PDF.

Ready to issue your first verifiable credential? Start free at badges.ninja — visual designer, public verification page, PDF certificate, Open Badge v2.0 output. No credit card required.

Nacho Coll

About the author

Founder & Engineer at Badges Ninja

Nacho founded Badges Ninja to make issuing verifiable digital credentials as simple as a single API call — Open Badge v2.0 badges and certificates, minted, hosted, and verifiable without standing up your own issuer infrastructure. Writes about the Open Badges spec, credential verification, and running a credentialing platform serverless on AWS, from the operator side of the wire.

Back to Blog

Related Posts