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 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.
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 akid(key id) that looks likedid:web:api.badges.ninja#<thumbprint>. - The payload holds the claims, including
iss(the issuer DIDdid:web:api.badges.ninja),jti(the credential id),nbf(valid from), an optionalexp(expiry), and avcobject with the actualOpenBadgeCredential. - 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.jsonreturns a JWK Set.https://api.badges.ninja/.well-known/did.jsonreturns the DID document fordid: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:
- Fetch the signed credential from the public endpoint.
- Split the token into its three parts.
- Read the header, check that
algis exactlyEdDSA, and take the thumbprint fromkid. - Fetch the JWKS and find the key whose
kidmatches. - Verify the Ed25519 signature over
header.payloadwith 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.

Quick reference
| Item | Value |
|---|---|
| Signed credential | GET https://api.badges.ninja/certify-badge/award/<awardId>/vc |
| Unsigned JSON for reading | same URL with ?format=json |
| Issuer DID | did:web:api.badges.ninja |
| Public keys | /.well-known/jwks.json and /.well-known/did.json |
| Algorithm | Ed25519 (EdDSA) |
| Key match | fragment of header kid equals JWKS kid |
| Revocation | credentialStatus 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.
How this article was made
Some posts on this blog are drafted with the help of an AI assistant and then reviewed, fact-checked, and edited by the Badges Ninja team before publishing. Every code sample and price is verified against the live product. Read more about our editorial and AI process on our editorial process page .

About the author
Nacho Coll
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.
More from Nacho Coll
- Coding Bootcamp Open Badges: Issuing Verifiable Credentials at Cohort ScaleNov 19, 2026 · 11min read
- Setting Up Webhooks for Badge Events: Real-Time Integration with Your BackendNov 16, 2026 · 9min read
- Open Badge Expiration and Renewal: Lifecycle Management for Time-Limited CredentialsNov 12, 2026 · 11min read


