Credentials API

Create and manage credentials (assertions) — badges issued to specific recipients.

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

Create Credential

Issue a badge to a recipient.

Need to issue to hundreds or thousands of recipients at once instead of one API call per person? Use the Bulk Credentials UI feature, which accepts a CSV upload.

POST /awards

Parameters

Parameter	Type	Required	Description
badgeId	string	Yes	The badge ID to issue
recipient	object	Yes	Recipient details (see below)
recipient.name	string	Yes	Recipient full name (minimum 5 characters)
recipient.email	string	Yes	Recipient email address
issuedOn	string	Yes	Issue date in ISO 8601 format (e.g. 2025-01-15)
expires	string	No	Expiration date in ISO 8601 format

Example

curl -X POST https://api.badges.ninja/awards \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "badgeId": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "recipient": {
        "name": "Jane Smith",
        "email": "jane@example.com"
      },
      "issuedOn": "2025-01-15"
    }
  }'

Response

{
  "awardId": "https://api.badges.ninja/certify-badge/award/c1d2e3f4-a5b6-7890-cdef-123456789012"
}

Notes

• Counts as one credential against your monthly quota (Free: 100/mo, Starter: 1,000/mo, Pro: 10,000/mo). The quota is measured against credentials created since 00:00 UTC on the 1st of the current calendar month — it resets on the UTC calendar-month boundary, not on your billing anniversary.

---

List Credentials

Retrieve credentials with optional filtering and pagination.

GET /awards

Query Parameters

Parameter	Type	Required	Description
filter	JSON string	No	Filter object (see below)
lastEvaluatedKey	string	No	Pagination token from a previous response

Filter Object

The filter parameter accepts a JSON string with these fields:

Field	Type	Description
badgeId	string	Filter by badge ID.
search	string	Substring to look up in either recipient names or emails (see searchField).
searchField	string	Either name (default) or email — which column to search.

Pagination via lastEvaluatedKey works with or without filters. Page size is 50.

Example — List All Credentials

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

Example — Filter by Badge

curl -X GET "https://api.badges.ninja/awards?filter=%7B%22badgeId%22%3A%22b1c2d3e4%22%7D" \
  -H "X-Api-Key: bws_your_api_key_here"

Response

{
  "count": 1,
  "items": [
    {
      "id": "https://api.badges.ninja/certify-badge/award/c1d2e3f4-...",
      "badge": {
        "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
        "name": "JavaScript Fundamentals",
        "image": "https://ipfs.ninja/ipfs/Qm..."
      },
      "recipient": {
        "name": "Jane Smith",
        "email": "jane@example.com"
      },
      "issuedOn": "2025-01-15T00:00:00.000Z",
      "timestamp": "2025-01-15T10:30:00.000Z"
    }
  ],
  "lastEvaluatedKey": "eyJ..."
}

If lastEvaluatedKey is present in the response, there are more results. Pass it as a query parameter in the next request to get the next page.

---

Send Credential Email

Send an email notification to a recipient about their credential.

POST /awards/{awardId}/send

Parameters

Parameter	Type	Required	Description
awardId	string	Yes	The award ID (path parameter and body)
email	string	Yes	Recipient email address

Example

curl -X POST https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/send \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "email": "jane@example.com"
    }
  }'

Response

Returns a plain confirmation string:

"email sent"

---

Share Credential

Share a credential with multiple recipients via email.

POST /awards/{awardId}/share

Parameters

Parameter	Type	Required	Description
awardId	string	Yes	The award ID (path parameter and body)
recipients	string	Yes	Comma-separated list of email addresses
subject	string	Yes	Email subject line
message	string	Yes	Email message body

Example

curl -X POST https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/share \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "recipients": "manager@example.com,hr@example.com",
      "subject": "Check out my new badge!",
      "message": "I just earned the JavaScript Fundamentals badge."
    }
  }'

Response

Returns a plain confirmation string:

"email sent"

---

Revoke Credential

Revoke a credential you issued. The hosted Open Badges v2.0 assertion is marked revoked: true (with an optional reason) so any verifier sees the badge is no longer valid. The credential record is kept for audit purposes, and no credit is refunded.

POST /awards/{awardId}/revoke

Parameters

Parameter	Type	Required	Description
awardId	string	Yes	The award ID (path parameter)
reason	string	No	Reason for revocation. Truncated to 500 characters.
notify	boolean	No	When true, emails the recipient that their credential was revoked. Defaults to false.

Example

curl -X POST https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/revoke \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "reason": "Issued to the wrong recipient",
      "notify": true
    }
  }'

Response

{
  "revoked": true,
  "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012"
}

Revoking an already-revoked credential is idempotent — it returns the same response without re-sending a notification.

---

Delete Credential

Hard-delete a credential you issued. Unlike revoke, this removes the record entirely and the public credential page will return 404. Use this for genuine mistakes (e.g. issued to the wrong person); prefer revoke for real credentials so the assertion stays verifiable as revoked. No credit is refunded.

DELETE /awards/{awardId}

Parameters

Parameter	Type	Required	Description
awardId	string	Yes	The award ID (path parameter)

Example

curl -X DELETE https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012 \
  -H "X-Api-Key: bws_your_api_key_here"

Response

{
  "deleted": true,
  "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012"
}

---

Download PDF Certificate

Generate a print-ready A4 PDF certificate for a credential.

GET /certify-badge/award/{awardGuid}/pdf

No authentication required — this endpoint is public so recipients can download their own certificate.

Example

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

The response is the binary PDF with a Content-Type: application/pdf header.

---

Track Credential Event

Record an engagement event. Used by the public credential page to populate engagement stats. No authentication required.

POST /certify-badge/award/{awardGuid}/event

Parameters

This endpoint reads its body directly (no parameters wrapper).

Parameter	Type	Required	Description
event	string	Yes	One of view, share, download, click_linkedin_addtoprofile, click_pdf, click_verify.
network	string	No	When event=share, the social network: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Per-IP duplicate suppression: the same event from the same IP is counted once per 24 hours.

Example

curl -X POST https://api.badges.ninja/certify-badge/award/c1d2e3f4-a5b6-7890-cdef-123456789012/event \
  -H "Content-Type: application/json" \
  -d '{"event": "share", "network": "linkedin"}'

Response

{
  "ok": true
}

---

Get Credential Stats

Retrieve cumulative engagement counters for a credential.

GET /certify-badge/award/{awardGuid}/stats

No authentication required.

Response

Counters are returned keyed by the raw event type. totals holds the total count per event; networks breaks down the per-network split for events that carry a network (currently share). Events with no recorded activity are simply absent.

{
  "totals": {
    "view": 142,
    "share": 16,
    "download": 3,
    "click_linkedin_addtoprofile": 4
  },
  "networks": {
    "share": { "linkedin": 8, "twitter": 2, "email": 1, "copy": 5 }
  }
}