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://ipfs.ninja/ipfs/Qm...",
  "issuer": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-..."
}

---

Get Award

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

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"
  }
}

Notes

• The recipient email is hashed (SHA-256) for privacy, following the Open Badge spec.
• Responses are cached for 1 hour (Cache-Control: public, max-age=3600).

---

Get Award Share Text

Retrieve the custom share text for an award'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 Award Email (Public)

Send an award 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
subject	string	No	Email subject
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"
}

---

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.