Issuers API

Manage badge issuers — the organizations or individuals that award badges.

All endpoints require authentication via the X-Api-Key header. See Authentication.

Create Issuer

Create a new badge issuer.

POST /issuers

Parameters

Parameter	Type	Required	Description
name	string	Yes	Organization name (minimum 3 characters)
url	string	Yes	Organization website (must be a valid HTTP/HTTPS URL)
email	string	Yes	Contact email for the issuer
logo	string	No	Base64-encoded image (PNG or JPG)
linkedinOrganizationId	string	No	Numeric LinkedIn company page ID. When set, every public award page from this issuer shows an Add to LinkedIn Profile button.

Example

curl -X POST https://api.badges.ninja/issuers \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "name": "Acme Academy",
      "url": "https://acme.example.com",
      "email": "badges@acme.example.com"
    }
  }'

Response

{
  "issuerId": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Notes

• Counts against your plan's issuer limit (Free: 1, Starter: 5, Pro: unlimited). No quota deduction.
• If the issuer email matches your account email, the issuer is auto-verified.
• If the email is different, a verification email is sent to the issuer email.
• After configuring an issuer, use the Awards API to start issuing credentials under that issuer.

---

List Issuers

Retrieve all issuers you have created.

GET /issuers

Example

curl -X GET https://api.badges.ninja/issuers \
  -H "X-Api-Key: bws_your_api_key_here"

Response

{
  "items": [
    {
      "id": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
      "name": "Acme Academy",
      "url": "https://acme.example.com",
      "email": "badges@acme.example.com",
      "verified": true,
      "timestamp": 1736937000000
    }
  ]
}

timestamp is a Unix epoch in milliseconds. When more issuers exist than fit in one page, a lastEvaluatedKey is also returned for pagination.

---

Verify Issuer

Verify an issuer using the verification code sent to its email.

POST /issuers/{issuerId}/verify

Parameters

Parameter	Type	Required	Description
issuerId	string	Yes	The issuer ID (path parameter)
code	string	Yes	The verification code from the email

Example

curl -X POST https://api.badges.ninja/issuers/a1b2c3d4-e5f6-7890-abcd-ef1234567890/verify \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "issuerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "code": "ABC123"
    }
  }'

Response

A bare string:

"issuer has been verified"

---

Delete Issuer

Delete an issuer. The issuer must have no badges linked to it.

DELETE /issuers/{issuerId}

Example

curl -X DELETE https://api.badges.ninja/issuers/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-Api-Key: bws_your_api_key_here"

Response

A bare string:

"issuer has been deleted"

Errors

• 400 — the issuer still has badges linked to it: issuer has {n} badge(s) linked — delete the badges first. Deletion is gated on linked badges only — awards do not block it.
• 404 — issuer not found

---

Update Issuer

Update an issuer's fields. Only unverified issuers can be edited — once an issuer is verified, this endpoint returns 400 verified issuers cannot be edited to preserve credential stability. Editing an issuer regenerates its verification code: if the email matches your account email the issuer is re-verified automatically, otherwise a fresh verification email is sent to that address.

PUT /issuers/{issuerId}

Parameters

Parameter	Type	Required	Description
issuerId	string	Yes	The issuer ID (path parameter)
name	string	No	New name
url	string	No	New URL
email	string	No	New email (sends a fresh verification mail unless it matches your account email)
logo	string	No	New base64-encoded logo
linkedinOrganizationId	string	No	New LinkedIn organization ID (or empty string to clear)

Response

{
  "issuerId": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
  "updated": true
}

Errors

• 400 — verified issuers cannot be edited (the issuer is already verified)
• 400 — not authorized (the issuer belongs to another account)
• 404 — issuer not found