Verificar a assinatura de um Open Badge em Node.js, Python e Go
Três exemplos de código funcionais (Node, Python, Go) para obter uma credencial Open Badge assinada, resolver a chave pública do emissor e verificar a assinatura 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.
Se emites credenciais, a maior parte do trabalho de verificação acontece sem ti: o destinatário partilha uma ligação, um empregador clica nela e a página de verificação faz o resto. Mas, mais cedo ou mais tarde, alguém faz uma pergunta mais incisiva: «Como sei que este ficheiro foi mesmo assinado por vocês e não foi alterado depois?» Essa pergunta responde-se com uma assinatura digital, e verificá-la dá cerca de quinze linhas de código em qualquer linguagem corrente.
Este tutorial mostra, passo a passo, como verificar uma credencial Open Badges 3.0 assinada e emitida através de https://badges.ninja, em Node.js, Python e Go. Não precisas de executar nada disto para emitir credenciais. É para quem quer auditar o sistema, criar uma ferramenta interna de verificação ou simplesmente perceber o que significa «verificável» na prática.
O que estás realmente a verificar
Existem duas camadas de verificação nos Open Badges, e convém mantê-las separadas.
A verificação alojada é o modelo do Open Badges 2.0. O prémio tem um URL público e qualquer pessoa que o abra vê o emissor, o emblema, a identidade com hash do destinatário e o estado. A confiança vem de os dados serem servidos a partir do domínio do próprio emissor. Se consegues aceder à página em https://badges.ninja, a credencial é real. Isto não exige código nem assinatura.
A verificação por assinatura é o modelo do Open Badges 3.0, assente nas Verifiable Credentials do W3C. A credencial é empacotada como um token assinado, pelo que pode ser verificada offline, anos mais tarde, mesmo que tenha sido copiada para uma carteira digital ou para um anexo de email. A confiança vem da matemática: o token traz uma assinatura que só o detentor da chave privada do emissor poderia ter produzido.
Em https://badges.ninja, cada prémio está disponível nas duas formas. Este artigo trata da segunda. Se queres perceber as diferenças entre as duas versões, lê Open Badges v2 vs v3 e, para uma visita guiada ao JSON alojado, vê o guia do JSON-LD de um Open Badge.
As peças em jogo
A credencial assinada é um VC-JWT: um JWS compacto, ou seja, três cadeias base64url separadas por pontos.
header.payload.signature
- O cabeçalho indica como foi assinada. Nas nossas credenciais contém
alg: EdDSA,typ: JWTe umkid(identificador da chave) com o aspetodid:web:api.badges.ninja#<thumbprint>. - O payload contém as declarações, incluindo
iss(o DID do emissordid:web:api.badges.ninja),jti(o id da credencial),nbf(válida a partir de), umexpopcional (validade) e um objetovccom aOpenBadgeCredentialpropriamente dita. - A assinatura é uma assinatura Ed25519 sobre os bytes exatos de
header.payload.
A chave pública que valida a assinatura é publicada pelo emissor em dois locais, ambos sem autenticação:
https://api.badges.ninja/.well-known/jwks.jsondevolve um JWK Set.https://api.badges.ninja/.well-known/did.jsondevolve o documento DID dedid:web:api.badges.ninja.
O kid do JWKS é o thumbprint RFC 7638 da chave. O kid no cabeçalho do token é o URL DID, e o seu fragmento (a parte depois de #) é esse mesmo thumbprint. Esse fragmento é o que te permite escolher a chave certa.
A receita de verificação
Todas as linguagens seguem os mesmos cinco passos:
- Obter a credencial assinada a partir do endpoint público.
- Dividir o token nas suas três partes.
- Ler o cabeçalho, confirmar que
algé exatamenteEdDSAe retirar o thumbprint dekid. - Obter o JWKS e encontrar a chave cujo
kidcorresponde. - Verificar a assinatura Ed25519 sobre
header.payloadcom essa chave.
O endpoint da credencial é público e recebe o id do prémio (o mesmo GUID que vês num URL de verificação como https://badges.ninja/awards/<awardId>):
curl https://api.badges.ninja/certify-badge/award/<awardId>/vc
Por defeito, devolve o VC-JWT assinado como application/jwt. Acrescenta ?format=json para obteres o JSON da credencial sem assinatura, para leitura. A referência de verificação documenta ambos.
Repara que não existe um endpoint separado do tipo «verifica isto por mim», e é de propósito. Um servidor que te diz «sim, é válido» pede-te que confies no servidor. O objetivo de uma assinatura é precisamente poderes verificá-la tu próprio com uma chave publicada.
Node.js
O módulo crypto incorporado no Node suporta Ed25519 e importação de JWK, por isso não precisas de dependências.
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);
O argumento null do algoritmo está correto: com Ed25519, o tipo de chave fixa o algoritmo. Se preferires uma biblioteca, a jose faz o mesmo trabalho com compactVerify e importJWK, e trata das verificações do cabeçalho por ti.
Python
O pacote cryptography dá-te Ed25519 diretamente. Instala-o com 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"])
O Python não tem importação de JWK para Ed25519 nesta biblioteca, por isso descodificamos nós a coordenada x (a chave pública em bruto de 32 bytes). É tudo o que um JWK do tipo OKP com a curva Ed25519 contém.
Go
A biblioteca padrão do Go cobre tudo, incluindo 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)
}
Executa com go run main.go <awardId>. O tratamento de erros foi reduzido para facilitar a leitura; numa ferramenta real, terias de verificar todas as descodificações.
Erros comuns e como os interpretar
A chave não é encontrada no JWKS. Comparaste o kid completo do cabeçalho do token (did:web:api.badges.ninja#abc) com o kid do JWKS (abc). Compara apenas o fragmento depois de #. Se o fragmento continuar a não corresponder, o emissor pode ter rodado as chaves desde que o token foi gerado; obtém o documento DID e consulta as suas entradas verificationMethod.
Assinatura inválida num token que acabaste de descarregar. Confirma que verificaste header.payload como o texto base64url original, e não JSON recodificado. Voltar a serializar o JSON altera os bytes e invalida a assinatura. Verifica também se há uma mudança de linha no fim do token descarregado.
Confusão de algoritmo. O ataque clássico a JWT é um token que declara alg: none ou muda para um algoritmo simétrico, para enganar o verificador e fazê-lo aceitá-lo. Os nossos exemplos evitam-no fixando no código o algoritmo esperado, EdDSA, e recusando todos os outros. Nunca deixes o token escolher como é verificado.
Erros de padding em Base64. O JWS usa base64url sem padding. O Python precisa que o padding seja reposto (como mostrado acima) e o Go precisa de RawURLEncoding, não de URLEncoding.
Assinatura válida, mas a credencial ainda é boa? Uma assinatura prova autenticidade e integridade, não o estado atual. Uma credencial pode estar corretamente assinada e, mesmo assim, estar revogada ou expirada. Verifica exp no payload e o estado de revogação descrito a seguir.
Não te esqueças da revogação
Cada credencial Open Badges 3.0 de https://badges.ninja inclui uma entrada credentialStatus que segue a Bitstring Status List do W3C. Aponta para uma credencial de lista de estado que podes obter em /certify-badge/status/<listId>. Quando um emissor revoga um prémio, um bit muda nessa lista; a lista fica em cache cerca de um minuto, por isso as revogações chegam depressa aos verificadores. Descodifica a lista e lê o bit em statusListIndex da credencial: 1 significa revogada, 0 significa ativa. A referência de verificação inclui um pequeno exemplo em Node dessa verificação do bit.
Um verificador completo faz três coisas: verifica a assinatura, verifica a validade e verifica o bit de revogação. Se quiseres ver como é a revogação do lado do emissor, a ação no painel está explicada no guia de prémios.
Quando não precisas de nada disto
A maioria dos responsáveis de programas nunca vai escrever este código, e está tudo bem. Para verificações do dia a dia, abre a página pública do prémio em https://badges.ninja/awards/<awardId> e lê-a. A página não exige registo nem chave e mostra o emissor, o emblema e o estado. Os destinatários também podem descarregar a Verifiable Credential a partir do menu Download da sua página pública de credencial e importá-la para qualquer carteira Open Badges 3.0.
A verificação de assinaturas torna-se valiosa quando:
- um empregador ou uma universidade quer automatizar a verificação das credenciais que recebe;
- estás a criar um sistema de registos que guarda cópias de credenciais e precisa de provar que não foram alteradas;
- um auditor pede provas de que as tuas credenciais são verificáveis de forma independente, e não apenas «confiem no nosso site».
A mesma configuração de chave de API usada para emitir não é necessária aqui, porque todos estes endpoints são públicos. Se quiseres mesmo emitir credenciais a partir de código, o guia rápido da API explica como criar uma chave e o teu primeiro prémio.

Referência rápida
| Item | Valor |
|---|---|
| Credencial assinada | GET https://api.badges.ninja/certify-badge/award/<awardId>/vc |
| JSON sem assinatura para leitura | o mesmo URL com ?format=json |
| DID do emissor | did:web:api.badges.ninja |
| Chaves públicas | /.well-known/jwks.json e /.well-known/did.json |
| Algoritmo | Ed25519 (EdDSA) |
| Correspondência da chave | o fragmento do kid do cabeçalho é igual ao kid do JWKS |
| Revogação | credentialStatus a apontar para /certify-badge/status/<listId> |
Para concluir
Verificar a assinatura de um Open Badge é uma rotina curta e mecânica: obter o token, fixar o algoritmo, encontrar a chave pelo thumbprint e verificar a assinatura Ed25519 sobre os dois primeiros segmentos. Acrescenta as verificações de validade e de revogação e tens um verificador que só confia na chave publicada do emissor. É essa independência que faz uma credencial digital valer mais do que um PDF.
Pronto para emitir a tua primeira credencial verificável? Começa de graça em badges.ninja — designer visual, página pública de verificação, certificado em PDF, saída Open Badge v2.0. Sem cartão de crédito.
Como este artigo foi feito
Alguns artigos deste blog são redigidos com a ajuda de um assistente de IA e depois revistos, verificados e editados pela equipa da Badges Ninja antes da publicação. Todos os exemplos de código e preços são verificados no produto em produção. Saiba mais sobre o nosso processo editorial e de IA na nossa página do processo editorial .

Sobre o 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.
Mais de Nacho Coll
- Open Badges para bootcamps de programação: emitir credenciais verificáveis à escala de uma turma19/11/2026 · 12min de leitura
- Configurar webhooks para eventos de emblemas: integração em tempo real com o teu backend16/11/2026 · 10min de leitura
- Expiração e renovação de Open Badges: gestão do ciclo de vida de credenciais com prazo de validade12/11/2026 · 12min de leitura


