Credentials-API

Skapa och hantera credentials (assertions) — märken som utfärdats till specifika mottagare.

Alla slutpunkter kräver autentisering via headern X-Api-Key. Se Autentisering.

Skapa credential

Utfärda ett märke till en mottagare.

Behöver du utfärda till hundratals eller tusentals mottagare på en gång i stället för ett API-anrop per person? Använd gränssnittsfunktionen Massutfärdade credentials, som tar emot en CSV-uppladdning.

POST /awards

Parametrar

Parameter	Typ	Obligatorisk	Beskrivning
badgeId	string	Ja	ID för märket som ska utfärdas
recipient	object	Ja	Mottagarens uppgifter (se nedan)
recipient.name	string	Ja	Mottagarens fullständiga namn (minst 5 tecken)
recipient.email	string	Ja	Mottagarens e-postadress
issuedOn	string	Ja	Utfärdandedatum i ISO 8601-format (t.ex. 2025-01-15)
expires	string	Nej	Utgångsdatum i ISO 8601-format

Exempel

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

Svar

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

Anmärkningar

• Räknas som en credential mot din årliga credential-pool (Free: 1 200/år, Starter: 12 000/år, Pro: 120 000/år). Poolen är en flexibel årlig kvot — använd den när du vill under året, även i omgångar — och nollställs på årsdagen av ditt kontos registrering. Faktureringen förblir månatlig; det är bara credential-kvoten som är årlig. Se Planer och fakturering för mer information.

---

Lista credentials

Hämta credentials med valfri filtrering och sidindelning.

GET /awards

Frågeparametrar

Parameter	Typ	Obligatorisk	Beskrivning
filter	JSON string	Nej	Filterobjekt (se nedan)
lastEvaluatedKey	string	Nej	Sidindelningstoken från ett tidigare svar

Filterobjekt

Parametern filter tar emot en JSON-sträng med följande fält:

Fält	Typ	Beskrivning
badgeId	string	Filtrera på märkes-ID.
search	string	Delsträng att söka efter i mottagarnas namn eller e-postadresser (se searchField).
searchField	string	Antingen name (standard) eller email — vilken kolumn som ska sökas.

Sidindelning via lastEvaluatedKey fungerar med eller utan filter. Sidstorleken är 50.

Exempel — lista alla credentials

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

Exempel — filtrera på märke

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"

Svar

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

Om lastEvaluatedKey finns i svaret finns det fler resultat. Skicka med den som frågeparameter i nästa anrop för att hämta nästa sida.

---

Skicka credential-e-post

Skicka ett e-postmeddelande till en mottagare om deras credential.

POST /awards/{awardId}/send

Parametrar

Parameter	Typ	Obligatorisk	Beskrivning
awardId	string	Ja	Award-ID:t (sökvägsparameter och body)
email	string	Ja	Mottagarens e-postadress

Exempel

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

Svar

Returnerar en enkel bekräftelsesträng:

"email sent"

---

Dela credential

Dela en credential med flera mottagare via e-post.

POST /awards/{awardId}/share

Parametrar

Parameter	Typ	Obligatorisk	Beskrivning
awardId	string	Ja	Award-ID:t (sökvägsparameter och body)
recipients	string	Ja	Kommaseparerad lista med e-postadresser
subject	string	Ja	E-postens ämnesrad
message	string	Ja	E-postmeddelandets text

Exempel

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

Svar

Returnerar en enkel bekräftelsesträng:

"email sent"

---

Återkalla credential

Återkalla en credential som du har utfärdat. Den hostade Open Badges v2.0-assertionen markeras med revoked: true (med en valfri orsak) så att alla verifierare ser att märket inte längre är giltigt. Credential-posten sparas för revisionsändamål och ingen kredit återbetalas.

Återkallelsen sprids också till credentialens Open Badges 3.0 Verifiable Credential: awardens bit växlas i den W3C Bitstring Status List som VC:ns credentialStatus refererar till, så att även VC-plånböcker upptäcker den. Se Återkallelse (Bitstring Status List).

POST /awards/{awardId}/revoke

Parametrar

Parameter	Typ	Obligatorisk	Beskrivning
awardId	string	Ja	Award-ID:t (sökvägsparameter)
reason	string	Nej	Orsak till återkallelsen. Kortas av till 500 tecken.
notify	boolean	Nej	När true meddelas mottagaren via e-post att credentialen har återkallats. Standard är false.

Exempel

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

Svar

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

Att återkalla en redan återkallad credential är idempotent — den returnerar samma svar utan att skicka ett nytt meddelande.

Återkalla i bulk

För att återkalla många credentials på en gång, använd den varaktiga bulk-slutpunkten med action: "revoke" i stället för att anropa den här slutpunkten 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 } }'

Den returnerar { "jobId", "total" }; jobbet återkallar varje ID på serversidan (och hoppar över redan återkallade) och kan återupptas. Redan återkallade och obefintliga ID:n rapporteras som överhoppade.

---

Ta bort credential

Radera en credential som du har utfärdat permanent. Till skillnad från återkallelse tar detta bort posten helt, och den publika credential-sidan returnerar 404. Använd detta för verkliga misstag (t.ex. utfärdad till fel person); föredra återkallelse för äkta credentials så att assertionen förblir verifierbar som återkallad. Ingen kredit återbetalas.

DELETE /awards/{awardId}

Parametrar

Parameter	Typ	Obligatorisk	Beskrivning
awardId	string	Ja	Award-ID:t (sökvägsparameter)

Exempel

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

Svar

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

---

Ladda ned PDF-certifikat

Generera ett utskriftsklart A4-PDF-certifikat för en credential.

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

Ingen autentisering krävs — slutpunkten är publik så att mottagare kan ladda ned sitt eget certifikat.

Exempel

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

Svaret är den binära PDF-filen med headern Content-Type: application/pdf.

---

Spåra credential-händelse

Registrera en engagemangshändelse. Används av den publika credential-sidan för att fylla engagemangsstatistiken. Ingen autentisering krävs.

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

Parametrar

Den här slutpunkten läser sin body direkt (ingen parameters-wrapper).

Parameter	Typ	Obligatorisk	Beskrivning
event	string	Ja	En av view, share, download, click_linkedin_addtoprofile, click_pdf, click_verify.
network	string	Nej	När event=share, det sociala nätverket: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Dubblettdämpning per IP: samma händelse från samma IP räknas en gång per 24 timmar.

Exempel

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

Svar

{
  "ok": true
}

---

Hämta credential-statistik

Hämta kumulativa engagemangsräknare för en credential.

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

Ingen autentisering krävs.

Svar

Räknarna returneras med den råa händelsetypen som nyckel. totals innehåller totalantalet per händelse; networks visar fördelningen per nätverk för händelser som har ett network (för närvarande share). Händelser utan registrerad aktivitet saknas helt enkelt.

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