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

{
  "statusCode": 200,
  "info": {
    "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.

---

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

{
  "statusCode": 200,
  "info": {
    "issuers": [
      {
        "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": "2025-01-15T10:30:00.000Z"
      }
    ]
  }
}

---

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

{
  "statusCode": 200,
  "info": {
    "verified": true
  }
}

---

Delete Issuer

Delete an issuer. The issuer must have no badges.

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

{
  "statusCode": 200,
  "info": {
    "deleted": true
  }
}

Errors

• 400 — issuer has badges or awards and cannot be deleted (delete those first)
• 404 — issuer not found

---

Update Issuer

Update an unverified issuer's fields. Once an issuer is verified, only logo and linkedinOrganizationId remain editable to preserve credential stability.

PUT /issuers/{issuerId}

Parameters

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

---

Rotate Verification Code

Invalidate the previous verification link and email a fresh one. Only valid while the issuer is still unverified.

POST /issuers/{issuerId}/rotate-code

Response

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