Cómo verificar la firma de una Open Badge en Node.js, Python y Go
Tres ejemplos de código funcionales (Node, Python, Go) para obtener una credencial Open Badge firmada, resolver la clave pública del emisor y verificar la firma JWS.
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.
Si emites credenciales, la mayor parte de la verificación ocurre sin que tengas que hacer nada: un destinatario comparte un enlace, un empleador hace clic y la página de verificación se encarga del resto. Pero tarde o temprano alguien te hará una pregunta más incisiva: «¿Cómo sé que este archivo lo firmaste realmente tú y que nadie lo editó después?». Esa pregunta la responde una firma digital, y comprobar una lleva unas quince líneas de código en cualquier lenguaje habitual.
Este tutorial muestra, paso a paso, cómo verificar una credencial Open Badges 3.0 firmada y emitida a través de https://badges.ninja, en Node.js, Python y Go. No necesitas ejecutar nada de esto para emitir credenciales. Es para quienes quieren auditar el sistema, crear una herramienta interna de verificación o, simplemente, entender qué significa «verificable» en la práctica.
Qué estás verificando realmente
En Open Badges hay dos capas de verificación, y conviene mantenerlas separadas.
La verificación alojada es el modelo de Open Badges 2.0. La insignia otorgada tiene una URL pública, y cualquiera que la abra ve el emisor, la insignia, la identidad con hash del destinatario y el estado. La confianza viene de que los datos se sirven desde el dominio del propio emisor. Si puedes llegar a la página en https://badges.ninja, la credencial es real. No requiere código ni firma.
La verificación de la firma es el modelo de Open Badges 3.0, basado en las Verifiable Credentials de W3C. La credencial se empaqueta como un token firmado, de modo que puede comprobarse sin conexión, años después, incluso si se copió a una cartera digital o a un adjunto de correo. La confianza viene de las matemáticas: el token lleva una firma que solo pudo producir quien posee la clave privada del emisor.
En https://badges.ninja, cada insignia otorgada está disponible en ambas formas. Este artículo trata de la segunda. Si quieres entender en qué se diferencian las dos versiones, lee Open Badges v2 vs v3, y para un recorrido por el JSON alojado, consulta el repaso del JSON-LD de Open Badge.
Las piezas del sistema
La credencial firmada es un VC-JWT: un JWS compacto, es decir, tres cadenas base64url separadas por puntos.
header.payload.signature
- El encabezado indica cómo se firmó. En nuestras credenciales contiene
alg: EdDSA,typ: JWTy unkid(identificador de clave) con el aspectodid:web:api.badges.ninja#<thumbprint>. - El payload contiene las afirmaciones, entre ellas
iss(el DID del emisordid:web:api.badges.ninja),jti(el id de la credencial),nbf(válida desde), unexpopcional (caducidad) y un objetovccon laOpenBadgeCredentialpropiamente dicha. - La firma es una firma Ed25519 sobre los bytes exactos de
header.payload.
La clave pública que comprueba la firma la publica el emisor en dos lugares, ambos sin autenticación:
https://api.badges.ninja/.well-known/jwks.jsondevuelve un JWK Set.https://api.badges.ninja/.well-known/did.jsondevuelve el documento DID dedid:web:api.badges.ninja.
El kid del JWKS es la huella (thumbprint) de la clave según RFC 7638. El kid del encabezado del token es la URL DID, y su fragmento (la parte después de #) es esa misma huella. Ese fragmento es lo que te permite elegir la clave correcta.
La receta de verificación
En todos los lenguajes se siguen los mismos cinco pasos:
- Obtén la credencial firmada desde el endpoint público.
- Divide el token en sus tres partes.
- Lee el encabezado, comprueba que
algsea exactamenteEdDSAy toma la huella dekid. - Obtén el JWKS y busca la clave cuyo
kidcoincida. - Verifica la firma Ed25519 sobre
header.payloadcon esa clave.
El endpoint de la credencial es público y recibe el id de la insignia otorgada (el mismo GUID que ves en una URL de verificación como https://badges.ninja/awards/<awardId>):
curl https://api.badges.ninja/certify-badge/award/<awardId>/vc
Por defecto devuelve el VC-JWT firmado como application/jwt. Añade ?format=json para obtener el JSON de la credencial sin firmar, para leerlo. La referencia de verificación documenta ambos.
Fíjate en que no existe un endpoint aparte del tipo «verifícamelo», y es deliberado. Un servidor que te dice «sí, es válida» te pide que confíes en el servidor. El sentido de una firma es que puedas comprobarla tú mismo con una clave publicada.
Node.js
El módulo crypto integrado de Node admite Ed25519 e importación de JWK, así que no necesitas dependencias.
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);
El argumento de algoritmo null es correcto: con Ed25519, el tipo de clave fija el algoritmo. Si prefieres una librería, jose hace el mismo trabajo con compactVerify e importJWK, y se encarga por ti de las comprobaciones del encabezado.
Python
El paquete cryptography te da Ed25519 directamente. Instálalo con 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 no tiene importación de JWK para Ed25519 en esta librería, así que decodificamos nosotros mismos la coordenada x (la clave pública en bruto de 32 bytes). Eso es todo lo que contiene un JWK de tipo OKP con curva Ed25519.
Go
La librería estándar de Go lo cubre todo, incluido 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)
}
Ejecútalo con go run main.go <awardId>. El manejo de errores está simplificado para facilitar la lectura; en una herramienta real comprobarías cada decodificación.
Errores comunes y cómo interpretarlos
La clave no aparece en el JWKS. Has comparado el kid completo del encabezado del token (did:web:api.badges.ninja#abc) con el kid del JWKS (abc). Compara solo el fragmento posterior a #. Si el fragmento sigue sin coincidir, es posible que el emisor haya rotado las claves desde que se generó el token; obtén el documento DID y revisa sus entradas verificationMethod.
Firma inválida en un token recién descargado. Comprueba que verificaste header.payload como el texto base64url original, no como JSON recodificado. Volver a serializar el JSON cambia los bytes y rompe la firma. Comprueba también que el token descargado no tenga un salto de línea al final.
Confusión de algoritmo. El ataque clásico a los JWT es un token que declara alg: none o cambia a un algoritmo simétrico para engañar al verificador y que lo acepte. Nuestros ejemplos lo evitan fijando en el código el algoritmo esperado, EdDSA, y rechazando todo lo demás. Nunca dejes que el token decida cómo se verifica.
Errores de relleno base64. JWS usa base64url sin relleno. Python necesita que se le añada el relleno (como se ve arriba), y Go necesita RawURLEncoding, no URLEncoding.
Firma válida, pero ¿sigue vigente la credencial? Una firma demuestra autenticidad e integridad, no el estado actual. Una credencial puede estar bien firmada y aun así estar revocada o caducada. Comprueba exp en el payload y revisa el estado de revocación que se describe a continuación.
No olvides la revocación
Toda credencial Open Badges 3.0 de https://badges.ninja incluye una entrada credentialStatus que sigue la Bitstring Status List de W3C. Apunta a una credencial de lista de estado que puedes obtener en /certify-badge/status/<listId>. Cuando un emisor revoca una insignia otorgada, se cambia un bit en esa lista; la lista se guarda en caché durante aproximadamente un minuto, de modo que las revocaciones llegan rápido a los verificadores. Decodifica la lista y lee el bit en el statusListIndex de la credencial: 1 significa revocada, 0 significa activa. La referencia de verificación incluye un breve ejemplo en Node de esa comprobación de bit.
Un verificador completo hace tres cosas: verifica la firma, comprueba la caducidad y comprueba el bit de revocación. Si quieres ver cómo se ve la revocación desde el lado del emisor, la acción del panel se explica en la guía de insignias otorgadas.
Cuándo no necesitas nada de esto
La mayoría de los responsables de programas nunca escribirán este código, y está bien. Para las comprobaciones del día a día, abre la página pública de la insignia en https://badges.ninja/awards/<awardId> y léela. La página no requiere registro ni clave, y muestra el emisor, la insignia y el estado. Los destinatarios también pueden descargar la Verifiable Credential desde el menú Descargar de su página pública de credencial e importarla en cualquier cartera compatible con Open Badges 3.0.
La comprobación de firmas resulta valiosa cuando:
- un empleador o una universidad quiere automatizar la comprobación de las credenciales que recibe;
- estás creando un sistema de registros que guarda copias de credenciales y necesita demostrar que no se alteraron;
- un auditor pide pruebas de que tus credenciales son verificables de forma independiente, y no solo «confía en nuestra web».
Aquí no hace falta la misma configuración de clave de API que se usa para emitir, porque todos estos endpoints son públicos. Si quieres emitir credenciales desde código, la guía rápida de la API te explica cómo crear una clave y tu primera insignia.

Referencia rápida
| Elemento | Valor |
|---|---|
| Credencial firmada | GET https://api.badges.ninja/certify-badge/award/<awardId>/vc |
| JSON sin firmar para lectura | la misma URL con ?format=json |
| DID del emisor | did:web:api.badges.ninja |
| Claves públicas | /.well-known/jwks.json y /.well-known/did.json |
| Algoritmo | Ed25519 (EdDSA) |
| Coincidencia de clave | el fragmento del kid del encabezado es igual al kid del JWKS |
| Revocación | credentialStatus que apunta a /certify-badge/status/<listId> |
Para terminar
Verificar la firma de una Open Badge es una rutina corta y mecánica: obtén el token, fija el algoritmo, busca la clave por su huella y comprueba la firma Ed25519 sobre los dos primeros segmentos. Añade las comprobaciones de caducidad y revocación y tendrás un verificador que no confía en nadie salvo en la clave publicada del emisor. Esa independencia es justo lo que hace que una credencial digital valga más que un PDF.
¿Listo para emitir tu primera credencial verificable? Empieza gratis en badges.ninja: diseñador visual, página pública de verificación, certificado en PDF, salida Open Badge v2.0. Sin tarjeta de crédito.
Cómo se elaboró este artículo
Algunos artículos de este blog se redactan con ayuda de un asistente de IA y luego son revisados, verificados y editados por el equipo de Badges Ninja antes de publicarse. Cada ejemplo de código y cada precio se verifican contra el producto en vivo. Más información sobre nuestro proceso editorial y de IA en nuestra página de proceso editorial .

Sobre el autor
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.
Más de Nacho Coll
- Open Badges para bootcamps de programación: credenciales verificables a escala de cohorte19 nov 2026 · 12min de lectura
- Configura webhooks para eventos de insignias: integración en tiempo real con tu backend16 nov 2026 · 10min de lectura
- Caducidad y renovación de Open Badges: gestión del ciclo de vida de credenciales con vigencia limitada12 nov 2026 · 12min de lectura


