Credentials API

Gumawa at mamahala ng mga kredensyal (assertion) — mga badge na ini-issue sa mga partikular na recipient.

Lahat ng endpoint ay nangangailangan ng authentication sa pamamagitan ng X-Api-Key header. Tingnan ang Authentication.

Gumawa ng Kredensyal

Mag-issue ng badge sa isang recipient.

Kailangan bang mag-issue sa daan-daan o libu-libong recipient nang sabay-sabay sa halip na isang API call kada tao? Gamitin ang Bulk Credentials UI feature, na tumatanggap ng CSV upload.

POST /awards

Mga Parameter

Parameter	Uri	Kailangan	Paglalarawan
`badgeId`	string	Oo	Ang badge ID na ii-issue
`recipient`	object	Oo	Mga detalye ng recipient (tingnan sa ibaba)
`recipient.name`	string	Oo	Buong pangalan ng recipient (hindi bababa sa 5 character)
`recipient.email`	string	Oo	Email address ng recipient
`issuedOn`	string	Oo	Petsa ng pag-issue sa ISO 8601 format (hal. `2025-01-15`)
`expires`	string	Hindi	Petsa ng pag-expire sa ISO 8601 format

Halimbawa

bash

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

json

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

Mga Tala

Bibilangin bilang isang kredensyal sa taunang credential pool mo (Free: 1,200/taon, Starter: 12,000/taon, Pro: 120,000/taon). Ang pool ay isang flexible na taunang allowance — gamitin ito kailan mo gusto sa loob ng taon, kasama ang sabay-sabay na paggamit — at nagre-reset sa anniversary ng pagpaparehistro ng account mo. Buwanan pa rin ang billing; ang credential quota lang ang taunan. Tingnan ang Plans & Billing para sa mga detalye.

Ilista ang mga Kredensyal

Kunin ang mga kredensyal na may opsyonal na filtering at pagination.

GET /awards

Mga Query Parameter

Parameter	Uri	Kailangan	Paglalarawan
`filter`	JSON string	Hindi	Filter object (tingnan sa ibaba)
`lastEvaluatedKey`	string	Hindi	Pagination token mula sa nakaraang response

Filter Object

Tumatanggap ang filter parameter ng JSON string na may mga sumusunod na field:

Field	Uri	Paglalarawan
`badgeId`	string	I-filter ayon sa badge ID.
`search`	string	Substring na hahanapin sa pangalan o email ng recipient (tingnan ang `searchField`).
`searchField`	string	Alinman sa `name` (default) o `email` — kung aling column ang hahanapan.

Gumagana ang pagination gamit ang lastEvaluatedKey mayroon man o walang filter. Ang laki ng page ay 50.

Halimbawa — Ilista ang Lahat ng Kredensyal

bash

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

Halimbawa — I-filter ayon sa Badge

bash

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

json

{
  "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://badges.ninja/images/{sha256}.png"
      },
      "recipient": {
        "name": "Jane Smith",
        "email": "jane@example.com"
      },
      "issuedOn": "2025-01-15T00:00:00.000Z",
      "timestamp": "2025-01-15T10:30:00.000Z"
    }
  ],
  "lastEvaluatedKey": "eyJ..."
}

Kung may lastEvaluatedKey sa response, may mga susunod pang resulta. Ipasa ito bilang query parameter sa susunod na request para makuha ang susunod na page.

Magpadala ng Email ng Kredensyal

Magpadala ng email notification sa recipient tungkol sa kanilang kredensyal.

POST /awards/{awardId}/send

Mga Parameter

Parameter	Uri	Kailangan	Paglalarawan
`awardId`	string	Oo	Ang award ID (path parameter at body)
`email`	string	Oo	Email address ng recipient

Halimbawa

bash

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

Nagbabalik ng simpleng confirmation string:

json

"email sent"

I-share ang kredensyal sa maraming recipient sa pamamagitan ng email.

POST /awards/{awardId}/share

Mga Parameter

Parameter	Uri	Kailangan	Paglalarawan
`awardId`	string	Oo	Ang award ID (path parameter at body)
`recipients`	string	Oo	Listahan ng mga email address na pinaghihiwalay ng kuwit
`subject`	string	Oo	Subject line ng email
`message`	string	Oo	Katawan ng email message

Halimbawa

bash

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

Nagbabalik ng simpleng confirmation string:

json

"email sent"

I-revoke ang Kredensyal

I-revoke ang kredensyal na ini-issue mo. Namamarkahan ang naka-host na Open Badges v2.0 assertion ng revoked: true (na may opsyonal na dahilan) para makita ng anumang verifier na hindi na valid ang badge. Pinananatili ang record ng kredensyal para sa audit, at walang ibabalik na credit.

Kumakalat din ang revocation sa Open Badges 3.0 Verifiable Credential ng kredensyal: ibinabaligtad ang bit ng award sa W3C Bitstring Status List na tinutukoy ng credentialStatus ng VC, kaya natutukoy rin ito ng mga VC wallet. Tingnan ang Revocation (Bitstring Status List).

POST /awards/{awardId}/revoke

Mga Parameter

Parameter	Uri	Kailangan	Paglalarawan
`awardId`	string	Oo	Ang award ID (path parameter)
`reason`	string	Hindi	Dahilan ng revocation. Pinuputol sa 500 character.
`notify`	boolean	Hindi	Kapag `true`, nag-e-email sa recipient na na-revoke ang kanilang kredensyal. Default ay `false`.

Halimbawa

bash

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

json

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

Idempotent ang pag-revoke ng kredensyal na na-revoke na — ibinabalik nito ang parehong response nang hindi nagpapadala muli ng notification.

Mag-revoke nang maramihan

Para mag-revoke ng maraming kredensyal nang sabay-sabay, gamitin ang durable bulk endpoint na may action: "revoke" sa halip na tawagin ang endpoint na ito kada award:

bash

curl -X POST https://api.badges.ninja/awards/bulk-send \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "parameters": { "action": "revoke", "awardIds": ["<id1>", "<id2>"], "reason": "Program cancelled", "notify": false } }'

Nagbabalik ito ng { "jobId", "total" }; nire-revoke ng job ang bawat id sa server (nilalaktawan ang mga na-revoke na) at maaaring ipagpatuloy. Ang mga na-revoke na at hindi umiiral na id ay iniuulat bilang skipped.

Burahin ang Kredensyal

Permanenteng burahin ang kredensyal na ini-issue mo. Hindi tulad ng revoke, tuluyang inaalis nito ang record at magbabalik ng 404 ang public credential page. Gamitin ito para sa tunay na pagkakamali (hal. na-issue sa maling tao); mas mainam ang revoke para sa mga tunay na kredensyal para manatiling verifiable ang assertion bilang revoked. Walang ibabalik na credit.

DELETE /awards/{awardId}

Mga Parameter

Parameter	Uri	Kailangan	Paglalarawan
`awardId`	string	Oo	Ang award ID (path parameter)

Halimbawa

bash

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

Response

json

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

I-download ang PDF Certificate

Gumawa ng print-ready na A4 PDF certificate para sa isang kredensyal.

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

Hindi kailangan ng authentication — public ang endpoint na ito para makapag-download ang mga recipient ng sarili nilang certificate.

Halimbawa

bash

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

Ang response ay ang binary PDF na may Content-Type: application/pdf header.

I-track ang Credential Event

Magtala ng engagement event. Ginagamit ng public credential page para punan ang engagement stats. Hindi kailangan ng authentication.

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

Mga Parameter

Direktang binabasa ng endpoint na ito ang body nito (walang parameters wrapper).

Parameter	Uri	Kailangan	Paglalarawan
`event`	string	Oo	Isa sa `view`, `share`, `download`, `click_linkedin_addtoprofile`, `click_pdf`, `click_verify`.
`network`	string	Hindi	Kapag `event=share`, ang social network: `linkedin`, `twitter`, `facebook`, `whatsapp`, `telegram`, `email`, `copy`.

Duplicate suppression kada IP: ang parehong event mula sa parehong IP ay isang beses lang binibilang kada 24 oras.

Halimbawa

bash

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

json

{
  "ok": true
}

Kunin ang Credential Stats

Kunin ang cumulative engagement counters ng isang kredensyal.

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

Hindi kailangan ng authentication.

Response

Ibinabalik ang mga counter na naka-key sa raw event type. Hawak ng totals ang kabuuang bilang kada event; ipinapakita naman ng networks ang hati kada network para sa mga event na may network (kasalukuyan ay share). Ang mga event na walang naitalang aktibidad ay hindi lilitaw.

json

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

Credentials API ​

Gumawa ng Kredensyal ​

Mga Parameter ​

Halimbawa ​

Response ​

Mga Tala ​

Ilista ang mga Kredensyal ​

Mga Query Parameter ​

Filter Object ​

Halimbawa — Ilista ang Lahat ng Kredensyal ​

Halimbawa — I-filter ayon sa Badge ​

Response ​

Magpadala ng Email ng Kredensyal ​

Mga Parameter ​

Halimbawa ​

Response ​

I-share ang Kredensyal ​

Mga Parameter ​

Halimbawa ​

Response ​

I-revoke ang Kredensyal ​

Mga Parameter ​

Halimbawa ​

Response ​

Mag-revoke nang maramihan ​

Burahin ang Kredensyal ​

Mga Parameter ​

Halimbawa ​

Response ​

I-download ang PDF Certificate ​

Halimbawa ​

I-track ang Credential Event ​

Mga Parameter ​

Halimbawa ​

Response ​

Kunin ang Credential Stats ​

Response ​

Credentials API

Gumawa ng Kredensyal

Mga Parameter

Halimbawa

Response

Mga Tala

Ilista ang mga Kredensyal

Mga Query Parameter

Filter Object

Halimbawa — Ilista ang Lahat ng Kredensyal

Halimbawa — I-filter ayon sa Badge

Response

Magpadala ng Email ng Kredensyal

Mga Parameter

Halimbawa

Response

I-share ang Kredensyal

Mga Parameter

Halimbawa

Response

I-revoke ang Kredensyal

Mga Parameter

Halimbawa

Response

Mag-revoke nang maramihan

Burahin ang Kredensyal

Mga Parameter

Halimbawa

Response

I-download ang PDF Certificate

Halimbawa

I-track ang Credential Event

Mga Parameter

Halimbawa

Response

Kunin ang Credential Stats

Response