Public Verification

These endpoints are public and do not require authentication. They allow anyone to verify badge credentials and retrieve Open Badge v2.0 JSON data.

All endpoints are relative to https://api.badges.ninja.

Get Issuer

Retrieve the Open Badge v2.0 Issuer Profile JSON for a given issuer.

GET /certify-badge/issuer/{guid}

Example

curl https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-e5f6-7890-abcd-ef1234567890

Response

{
  "@context": "https://w3id.org/openbadges/v2",
  "type": "Issuer",
  "id": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
  "name": "Acme Academy",
  "url": "https://acme.example.com",
  "email": "badges@acme.example.com",
  "verification": {
    "type": "hosted",
    "allowedOrigins": "api.badges.ninja"
  }
}

---

Get Badge

Retrieve the Open Badge v2.0 BadgeClass JSON for a given badge.

GET /certify-badge/badge/{guid}

Example

curl https://api.badges.ninja/certify-badge/badge/b1c2d3e4-f5a6-7890-bcde-f12345678901

Response

{
  "@context": "https://w3id.org/openbadges/v2",
  "type": "BadgeClass",
  "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
  "name": "JavaScript Fundamentals",
  "description": "Demonstrates proficiency in core JavaScript concepts",
  "criteria": {
    "narrative": "Completed the JavaScript Fundamentals course with a score of 80% or higher"
  },
  "image": "https://badges.ninja/images/{sha256}.png",
  "issuer": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-..."
}

---

Get Credential

Retrieve the Open Badge v2.0 Assertion JSON for a given credential.

GET /certify-badge/award/{guid}

Example

curl https://api.badges.ninja/certify-badge/award/c1d2e3f4-a5b6-7890-cdef-123456789012

Response

{
  "@context": "https://w3id.org/openbadges/v2",
  "type": "Assertion",
  "id": "https://api.badges.ninja/certify-badge/award/c1d2e3f4-...",
  "recipient": {
    "type": "email",
    "hashed": true,
    "identity": "sha256$..."
  },
  "badge": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
  "issuedOn": "2025-01-15T00:00:00.000Z",
  "verification": {
    "type": "hosted"
  },
  "revoked": false
}

If the credential has been revoked, the assertion carries "revoked": true and, when a reason was given, a "revocationReason" string:

{
  "revoked": true,
  "revocationReason": "Issued in error"
}

This is the Open Badges 2.0 view of revocation. The same revocation is also expressed in the credential's Open Badges 3.0 Verifiable Credential — see Revocation (Bitstring Status List).

Notes

• The recipient email is hashed (SHA-256) for privacy, following the Open Badge spec.
• Responses are cached for 5 minutes (Cache-Control: public, max-age=300). Revoked credentials use a shorter 30-second cache (max-age=30) so revocation propagates quickly.

---

Get Credential Share Text

Retrieve the custom share text for a credential's badge.

GET /certify-badge/award/{guid}/share-text

Example

curl https://api.badges.ninja/certify-badge/award/c1d2e3f4-a5b6-7890-cdef-123456789012/share-text

Response

{
  "text": "I just earned the JavaScript Fundamentals badge! Check it out:"
}

If no custom share text is set, a default message is returned.

---

Send Credential Email (Public)

Send a credential notification email from the public endpoint. This is used by the public share page.

POST /certify-badge/award/{guid}/send-email

Parameters

Parameter	Type	Required	Description
recipients	string	Yes	Comma-separated list of email addresses
message	string	No	Custom message to include in the email

Example

curl -X POST https://api.badges.ninja/certify-badge/award/c1d2e3f4-a5b6-7890-cdef-123456789012/send-email \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "recipients": "colleague@example.com",
      "message": "Check out this badge!"
    }
  }'

Response

{
  "statusCode": 200,
  "info": "award sent"
}

This is the only endpoint that wraps its result in a { "statusCode", "info" } envelope. Every other endpoint returns its payload directly.

---

Verify Issuer

Verify an issuer by clicking the verification link sent to the issuer email. This is typically accessed via the link in the verification email, not called directly.

GET /certify-badge/verify-issuer/{guid}/{code}

Parameters

Parameter	Type	Description
guid	string	The issuer GUID
code	string	The verification code

Response

Returns an HTML page confirming the verification succeeded or failed. This endpoint is designed to be opened in a browser.