Bevis-API

Opprett og administrer bevis (assertions) — merker utstedt til spesifikke mottakere.

Alle endepunkter krever autentisering via X-Api-Key-headeren. Se Autentisering.

Opprett bevis

Utsted et merke til en mottaker.

Trenger du å utstede til hundrevis eller tusenvis av mottakere samtidig i stedet for ett API-kall per person? Bruk UI-funksjonen Massebevis, som godtar CSV-opplasting.

POST /awards

Parametere

Parameter	Type	Påkrevd	Beskrivelse
badgeId	string	Ja	ID-en til merket som skal utstedes
recipient	object	Ja	Mottakerdetaljer (se nedenfor)
recipient.name	string	Ja	Mottakerens fulle navn (minst 5 tegn)
recipient.email	string	Ja	Mottakerens e-postadresse
issuedOn	string	Ja	Utstedelsesdato i ISO 8601-format (f.eks. 2025-01-15)
expires	string	Nei	Utløpsdato i ISO 8601-format

Eksempel

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

Merknader

• Teller som ett bevis mot din årlige bevispool (Free: 1 200/år, Starter: 12 000/år, Pro: 120 000/år). Poolen er en fleksibel årlig kvote — bruk den når du vil gjennom året, også i rykk og napp — og nullstilles på årsdagen for kontoens registrering. Fakturering forblir månedlig; bare bevis-kvoten er årlig. Se Planer og fakturering for detaljer.

---

List bevis

Hent bevis med valgfri filtrering og paginering.

GET /awards

Spørringsparametere

Parameter	Type	Påkrevd	Beskrivelse
filter	JSON string	Nei	Filterobjekt (se nedenfor)
lastEvaluatedKey	string	Nei	Pagineringstoken fra et tidligere svar

Filterobjekt

Parameteren filter godtar en JSON-streng med disse feltene:

Felt	Type	Beskrivelse
badgeId	string	Filtrer etter merke-ID.
search	string	Delstreng å slå opp i mottakernavn eller e-postadresser (se searchField).
searchField	string	Enten name (standard) eller email — hvilken kolonne det søkes i.

Paginering via lastEvaluatedKey fungerer med eller uten filtre. Sidestørrelsen er 50.

Eksempel — list alle bevis

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

Eksempel — filtrer etter merke

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

Hvis lastEvaluatedKey finnes i svaret, er det flere resultater. Send den som spørringsparameter i neste forespørsel for å hente neste side.

---

Send bevis på e-post

Send et e-postvarsel til en mottaker om beviset deres.

POST /awards/{awardId}/send

Parametere

Parameter	Type	Påkrevd	Beskrivelse
awardId	string	Ja	Bevis-ID-en (stiparameter og body)
email	string	Ja	Mottakerens e-postadresse

Eksempel

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

Returnerer en vanlig bekreftelsesstreng:

"email sent"

---

Del bevis

Del et bevis med flere mottakere via e-post.

POST /awards/{awardId}/share

Parametere

Parameter	Type	Påkrevd	Beskrivelse
awardId	string	Ja	Bevis-ID-en (stiparameter og body)
recipients	string	Ja	Kommaseparert liste over e-postadresser
subject	string	Ja	Emnelinje for e-posten
message	string	Ja	Meldingsteksten i e-posten

Eksempel

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

Returnerer en vanlig bekreftelsesstreng:

"email sent"

---

Tilbakekall bevis

Tilbakekall et bevis du har utstedt. Den vertede Open Badges v2.0-assertionen merkes med revoked: true (med en valgfri årsak), slik at alle verifikatorer ser at merket ikke lenger er gyldig. Bevisposten beholdes av hensyn til revisjon, og ingen kreditt refunderes.

Tilbakekallingen forplanter seg også til beviset sin Open Badges 3.0 Verifiable Credential: bevisets bit snus i W3C Bitstring Status List som VC-ens credentialStatus refererer til, slik at VC-lommebøker også oppdager det. Se Tilbakekalling (Bitstring Status List).

POST /awards/{awardId}/revoke

Parametere

Parameter	Type	Påkrevd	Beskrivelse
awardId	string	Ja	Bevis-ID-en (stiparameter)
reason	string	Nei	Årsak til tilbakekallingen. Avkortes til 500 tegn.
notify	boolean	Nei	Når true, sendes en e-post til mottakeren om at beviset er tilbakekalt. Standard er false.

Eksempel

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

Å tilbakekalle et bevis som allerede er tilbakekalt, er idempotent — det returnerer det samme svaret uten å sende varselet på nytt.

Tilbakekall i bulk

For å tilbakekalle mange bevis samtidig bruker du det varige bulk-endepunktet med action: "revoke" i stedet for å kalle dette endepunktet per bevis:

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

Det returnerer { "jobId", "total" }; jobben tilbakekaller hver id på serversiden (hopper over de som allerede er tilbakekalt) og kan gjenopptas. ID-er som allerede er tilbakekalt eller ikke finnes, rapporteres som hoppet over.

---

Slett bevis

Slett et bevis du har utstedt permanent. I motsetning til tilbakekalling fjerner dette posten helt, og den offentlige bevissiden returnerer 404. Bruk dette for ekte feil (f.eks. utstedt til feil person); foretrekk tilbakekalling for ekte bevis, slik at assertionen forblir verifiserbar som tilbakekalt. Ingen kreditt refunderes.

DELETE /awards/{awardId}

Parametere

Parameter	Type	Påkrevd	Beskrivelse
awardId	string	Ja	Bevis-ID-en (stiparameter)

Eksempel

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

---

Last ned PDF-sertifikat

Generer et utskriftsklart A4-PDF-sertifikat for et bevis.

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

Ingen autentisering kreves — dette endepunktet er offentlig, slik at mottakere kan laste ned sitt eget sertifikat.

Eksempel

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

Svaret er den binære PDF-en med headeren Content-Type: application/pdf.

---

Spor bevishendelse

Registrer en engasjementshendelse. Brukes av den offentlige bevissiden til å fylle engasjementsstatistikken. Ingen autentisering kreves.

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

Parametere

Dette endepunktet leser body direkte (ingen parameters-omslag).

Parameter	Type	Påkrevd	Beskrivelse
event	string	Ja	En av view, share, download, click_linkedin_addtoprofile, click_pdf, click_verify.
network	string	Nei	Når event=share, det sosiale nettverket: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Duplikatundertrykking per IP: den samme hendelsen fra samme IP telles én gang per 24 timer.

Eksempel

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
}

---

Hent bevisstatistikk

Hent kumulative engasjementstellere for et bevis.

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

Ingen autentisering kreves.

Svar

Tellerne returneres nøklet på den rå hendelsestypen. totals inneholder totalt antall per hendelse; networks viser fordelingen per nettverk for hendelser som har network (for øyeblikket share). Hendelser uten registrert aktivitet er rett og slett utelatt.

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