Firma y verificación

badges.ninja publica una identidad criptográfica pública para que terceros puedan verificar las credenciales que llevan una firma digital. Esta es la base de la compatibilidad con Open Badges 3.0 / W3C Verifiable Credentials.

Estos endpoints son públicos y no requieren autenticación. Son relativos a https://api.badges.ninja.

DID del emisor

La identidad del emisor de la plataforma es el identificador did:web:

did:web:api.badges.ninja

Según las reglas de did:web, esto se resuelve en el documento DID servido en la ruta well-known que aparece más abajo.

Documento DID

GET /.well-known/did.json

Devuelve el documento DID que expone la clave pública de firma del emisor (una JsonWebKey2020 Ed25519) como su assertionMethod.

curl https://api.badges.ninja/.well-known/did.json

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/jws-2020/v1"
  ],
  "id": "did:web:api.badges.ninja",
  "verificationMethod": [
    {
      "id": "did:web:api.badges.ninja#<kid>",
      "type": "JsonWebKey2020",
      "controller": "did:web:api.badges.ninja",
      "publicKeyJwk": { "kty": "OKP", "crv": "Ed25519", "x": "<base64url>" }
    }
  ],
  "assertionMethod": ["did:web:api.badges.ninja#<kid>"],
  "authentication": ["did:web:api.badges.ninja#<kid>"]
}

El tipo de contenido de la respuesta es application/did+json. El documento es cacheable (solo cambia al rotar la clave).

JWKS

Para los verificadores que prefieren el descubrimiento por JWK Set en lugar de la resolución DID:

GET /.well-known/jwks.json

curl https://api.badges.ninja/.well-known/jwks.json

{
  "keys": [
    {
      "kty": "OKP",
      "crv": "Ed25519",
      "x": "<base64url>",
      "kid": "<thumbprint>",
      "alg": "EdDSA",
      "use": "sig"
    }
  ]
}

El kid es el thumbprint RFC 7638 de la clave pública y coincide con el fragmento del id de verificationMethod del documento DID.

Credencial verificable (Open Badges 3.0)

Cada credencial se puede obtener como una Open Badges 3.0 / W3C Verifiable Credential, firmada con la clave del emisor que aparece más arriba.

GET /certify-badge/award/{guid}/vc

Consulta	Resultado
(por defecto) o ?format=jwt	El VC-JWT firmado (application/jwt) — impórtalo a una cartera OB 3.0.
?format=json	El JSON OpenBadgeCredential sin firmar (application/vc+ld+json) — para inspección.

# Signed credential (VC-JWT)
curl https://api.badges.ninja/certify-badge/award/<guid>/vc

# Human-readable credential JSON
curl "https://api.badges.ninja/certify-badge/award/<guid>/vc?format=json"

La credencial es una VC con tipo ["VerifiableCredential", "OpenBadgeCredential"] (contextos https://www.w3.org/ns/credentials/v2 y el contexto OB 3.0). Su issuer.id es did:web:api.badges.ninja, y el logro, la identidad del destinatario (correo con hash) y las fechas de emisión/caducidad provienen de la credencial.

Verificar un VC-JWT

El token es un JWS compacto con una firma EdDSA. Para verificarlo:

1. Divide el JWT en header.payload.signature.
2. Lee el kid de la cabecera — apunta al documento DID / JWKS.
3. Obtén la clave pública y verifica la firma Ed25519 sobre header.payload.

import crypto from "node:crypto";

const [h, p, s] = jwt.split(".");
const jwks = await (await fetch("https://api.badges.ninja/.well-known/jwks.json")).json();
const jwk = jwks.keys[0];
const pub = crypto.createPublicKey({ key: jwk, format: "jwk" });
const ok = crypto.verify(null, Buffer.from(`${h}.${p}`), pub, Buffer.from(s, "base64url"));

Los destinatarios también pueden obtener la credencial desde el menú Download en su página pública de credencial (Verifiable Credential).

Algoritmo de firma

Las firmas usan Ed25519 (EdDSA). La clave privada se custodia en el servidor y nunca se expone; solo se publica la clave pública que aparece más arriba.

Verificación alojada (Open Badges 2.0)

Cada credencial también es verificable de forma independiente hoy mismo mediante su assertion alojada de Open Badge 2.0. Consulta Verificación pública para los endpoints JSON de assertion, insignia y emisor, y Compartir y verificar para la página de verificación orientada al destinatario.