API Kredensial

Buat dan kelola kredensial (assertion) — lencana yang diterbitkan kepada penerima tertentu.

Semua endpoint memerlukan autentikasi melalui header X-Api-Key. Lihat Autentikasi.

Buat Kredensial

Terbitkan lencana kepada seorang penerima.

Perlu menerbitkan kepada ratusan atau ribuan penerima sekaligus, bukan satu panggilan API per orang? Gunakan fitur UI Kredensial Massal, yang menerima unggahan CSV.

POST /awards

Parameter

Parameter	Tipe	Wajib	Deskripsi
badgeId	string	Ya	ID lencana yang akan diterbitkan
recipient	object	Ya	Detail penerima (lihat di bawah)
recipient.name	string	Ya	Nama lengkap penerima (minimal 5 karakter)
recipient.email	string	Ya	Alamat surel penerima
issuedOn	string	Ya	Tanggal penerbitan dalam format ISO 8601 (mis. 2025-01-15)
expires	string	Tidak	Tanggal kedaluwarsa dalam format ISO 8601

Contoh

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

Respons

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

Catatan

• Dihitung sebagai satu kredensial dari kuota kredensial tahunan Anda (Free: 1.200/tahun, Starter: 12.000/tahun, Pro: 120.000/tahun). Kuota ini adalah jatah tahunan yang fleksibel — gunakan kapan pun Anda mau sepanjang tahun, termasuk sekaligus dalam jumlah besar — dan direset pada hari jadi pendaftaran akun Anda. Penagihan tetap bulanan; hanya kuota kredensial yang tahunan. Lihat Paket & Penagihan untuk detailnya.

---

Daftar Kredensial

Ambil kredensial dengan pemfilteran dan paginasi opsional.

GET /awards

Parameter Kueri

Parameter	Tipe	Wajib	Deskripsi
filter	string JSON	Tidak	Objek filter (lihat di bawah)
lastEvaluatedKey	string	Tidak	Token paginasi dari respons sebelumnya

Objek Filter

Parameter filter menerima string JSON dengan field berikut:

Field	Tipe	Deskripsi
badgeId	string	Filter berdasarkan ID lencana.
search	string	Substring yang dicari pada nama atau surel penerima (lihat searchField).
searchField	string	name (default) atau email — kolom mana yang dicari.

Paginasi melalui lastEvaluatedKey berfungsi dengan maupun tanpa filter. Ukuran halaman adalah 50.

Contoh — Daftar Semua Kredensial

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

Contoh — Filter berdasarkan Lencana

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"

Respons

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

Jika lastEvaluatedKey ada dalam respons, berarti masih ada hasil lainnya. Sertakan sebagai parameter kueri pada permintaan berikutnya untuk mendapatkan halaman selanjutnya.

---

Kirim Surel Kredensial

Kirim pemberitahuan surel kepada penerima tentang kredensialnya.

POST /awards/{awardId}/send

Parameter

Parameter	Tipe	Wajib	Deskripsi
awardId	string	Ya	ID award (parameter path dan body)
email	string	Ya	Alamat surel penerima

Contoh

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

Respons

Mengembalikan string konfirmasi biasa:

"email sent"

---

Bagikan Kredensial

Bagikan kredensial kepada beberapa penerima melalui surel.

POST /awards/{awardId}/share

Parameter

Parameter	Tipe	Wajib	Deskripsi
awardId	string	Ya	ID award (parameter path dan body)
recipients	string	Ya	Daftar alamat surel dipisahkan koma
subject	string	Ya	Baris subjek surel
message	string	Ya	Isi pesan surel

Contoh

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

Respons

Mengembalikan string konfirmasi biasa:

"email sent"

---

Cabut Kredensial

Cabut kredensial yang Anda terbitkan. Assertion Open Badges v2.0 yang di-host ditandai revoked: true (dengan alasan opsional) sehingga setiap verifikator melihat bahwa lencana tidak lagi valid. Catatan kredensial tetap disimpan untuk keperluan audit, dan tidak ada kredit yang dikembalikan.

Pencabutan juga diteruskan ke Verifiable Credential Open Badges 3.0 milik kredensial tersebut: bit award dibalik pada W3C Bitstring Status List yang dirujuk oleh credentialStatus milik VC, sehingga dompet VC juga mendeteksinya. Lihat Pencabutan (Bitstring Status List).

POST /awards/{awardId}/revoke

Parameter

Parameter	Tipe	Wajib	Deskripsi
awardId	string	Ya	ID award (parameter path)
reason	string	Tidak	Alasan pencabutan. Dipotong hingga 500 karakter.
notify	boolean	Tidak	Jika true, mengirim surel kepada penerima bahwa kredensialnya telah dicabut. Default false.

Contoh

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

Respons

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

Mencabut kredensial yang sudah dicabut bersifat idempoten — mengembalikan respons yang sama tanpa mengirim ulang pemberitahuan.

Cabut secara massal

Untuk mencabut banyak kredensial sekaligus, gunakan endpoint massal yang tahan lama dengan action: "revoke" alih-alih memanggil endpoint ini per award:

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

Endpoint ini mengembalikan { "jobId", "total" }; job mencabut setiap id di sisi server (melewati yang sudah dicabut) dan dapat dilanjutkan. Id yang sudah dicabut dan yang tidak ada dilaporkan sebagai dilewati.

---

Hapus Kredensial

Hapus permanen kredensial yang Anda terbitkan. Berbeda dengan pencabutan, ini menghapus catatan sepenuhnya dan halaman kredensial publik akan mengembalikan 404. Gunakan untuk kesalahan yang nyata (mis. diterbitkan kepada orang yang salah); untuk kredensial sungguhan, utamakan cabut agar assertion tetap dapat diverifikasi sebagai dicabut. Tidak ada kredit yang dikembalikan.

DELETE /awards/{awardId}

Parameter

Parameter	Tipe	Wajib	Deskripsi
awardId	string	Ya	ID award (parameter path)

Contoh

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

Respons

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

---

Unduh Sertifikat PDF

Buat sertifikat PDF A4 siap cetak untuk sebuah kredensial.

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

Tidak memerlukan autentikasi — endpoint ini bersifat publik sehingga penerima dapat mengunduh sertifikat mereka sendiri.

Contoh

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

Respons berupa PDF biner dengan header Content-Type: application/pdf.

---

Lacak Event Kredensial

Catat sebuah event keterlibatan. Digunakan oleh halaman kredensial publik untuk mengisi statistik keterlibatan. Tidak memerlukan autentikasi.

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

Parameter

Endpoint ini membaca body-nya secara langsung (tanpa pembungkus parameters).

Parameter	Tipe	Wajib	Deskripsi
event	string	Ya	Salah satu dari view, share, download, click_linkedin_addtoprofile, click_pdf, click_verify.
network	string	Tidak	Saat event=share, jejaring sosialnya: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Penekanan duplikat per IP: event yang sama dari IP yang sama dihitung sekali per 24 jam.

Contoh

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

Respons

{
  "ok": true
}

---

Dapatkan Statistik Kredensial

Ambil penghitung keterlibatan kumulatif untuk sebuah kredensial.

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

Tidak memerlukan autentikasi.

Respons

Penghitung dikembalikan dengan kunci berupa tipe event mentah. totals berisi jumlah total per event; networks merinci pembagian per jejaring untuk event yang membawa network (saat ini share). Event tanpa aktivitas tercatat tidak akan muncul.

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