API delle credenziali

Crea e gestisci le credenziali (assertion) — badge emessi a destinatari specifici.

Tutti gli endpoint richiedono l'autenticazione tramite l'header X-Api-Key. Vedi Autenticazione.

Crea credenziale

Emetti un badge a un destinatario.

Devi emettere a centinaia o migliaia di destinatari in una volta, invece di una chiamata API per persona? Usa la funzione dell'interfaccia Credenziali in blocco, che accetta il caricamento di un CSV.

POST /awards

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
badgeId	string	Sì	L'ID del badge da emettere
recipient	object	Sì	Dettagli del destinatario (vedi sotto)
recipient.name	string	Sì	Nome completo del destinatario (minimo 5 caratteri)
recipient.email	string	Sì	Indirizzo e-mail del destinatario
issuedOn	string	Sì	Data di emissione in formato ISO 8601 (es. 2025-01-15)
expires	string	No	Data di scadenza in formato ISO 8601

Esempio

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

Risposta

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

Note

• Conta come una credenziale sul tuo pool annuale di credenziali (Free: 1.200/anno, Starter: 12.000/anno, Pro: 120.000/anno). Il pool è una disponibilità annuale flessibile — usala quando vuoi nel corso dell'anno, anche a raffiche — e si azzera alla data di anniversario della registrazione del tuo account. La fatturazione resta mensile; solo la quota di credenziali è annuale. Vedi Piani e fatturazione per i dettagli.

---

Elenca le credenziali

Recupera le credenziali con filtri e paginazione facoltativi.

GET /awards

Parametri di query

Parametro	Tipo	Obbligatorio	Descrizione
filter	stringa JSON	No	Oggetto filtro (vedi sotto)
lastEvaluatedKey	string	No	Token di paginazione da una risposta precedente

Oggetto filtro

Il parametro filter accetta una stringa JSON con questi campi:

Campo	Tipo	Descrizione
badgeId	string	Filtra per ID del badge.
search	string	Sottostringa da cercare nei nomi o nelle e-mail dei destinatari (vedi searchField).
searchField	string	name (predefinito) oppure email — quale colonna cercare.

La paginazione tramite lastEvaluatedKey funziona con o senza filtri. La dimensione della pagina è 50.

Esempio — Elenca tutte le credenziali

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

Esempio — Filtra per 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"

Risposta

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

Se lastEvaluatedKey è presente nella risposta, ci sono altri risultati. Passalo come parametro di query nella richiesta successiva per ottenere la pagina seguente.

---

Invia e-mail della credenziale

Invia a un destinatario una notifica e-mail relativa alla sua credenziale.

POST /awards/{awardId}/send

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
awardId	string	Sì	L'ID dell'award (parametro di percorso e body)
email	string	Sì	Indirizzo e-mail del destinatario

Esempio

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

Risposta

Restituisce una semplice stringa di conferma:

"email sent"

---

Condividi credenziale

Condividi una credenziale con più destinatari via e-mail.

POST /awards/{awardId}/share

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
awardId	string	Sì	L'ID dell'award (parametro di percorso e body)
recipients	string	Sì	Elenco di indirizzi e-mail separati da virgola
subject	string	Sì	Oggetto dell'e-mail
message	string	Sì	Corpo del messaggio e-mail

Esempio

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

Risposta

Restituisce una semplice stringa di conferma:

"email sent"

---

Revoca credenziale

Revoca una credenziale che hai emesso. L'assertion Open Badges v2.0 ospitata viene contrassegnata con revoked: true (con un motivo facoltativo), così qualsiasi verificatore vede che il badge non è più valido. Il record della credenziale viene conservato per scopi di audit e non viene rimborsato alcun credito.

La revoca si propaga anche alla Verifiable Credential Open Badges 3.0 della credenziale: il bit dell'award viene invertito nella W3C Bitstring Status List a cui rimanda il credentialStatus della VC, così anche i wallet VC la rilevano. Vedi Revoca (Bitstring Status List).

POST /awards/{awardId}/revoke

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
awardId	string	Sì	L'ID dell'award (parametro di percorso)
reason	string	No	Motivo della revoca. Troncato a 500 caratteri.
notify	boolean	No	Se true, invia al destinatario un'e-mail che lo informa della revoca della credenziale. Il valore predefinito è false.

Esempio

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

Risposta

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

Revocare una credenziale già revocata è idempotente — restituisce la stessa risposta senza inviare di nuovo la notifica.

Revoca in blocco

Per revocare molte credenziali in una volta, usa l'endpoint durevole per operazioni in blocco con action: "revoke" invece di chiamare questo endpoint per ogni 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 } }'

Restituisce { "jobId", "total" }; il job revoca ogni id lato server (saltando quelli già revocati) ed è riprendibile. Gli id già revocati e quelli inesistenti vengono segnalati come saltati.

---

Elimina credenziale

Elimina definitivamente una credenziale che hai emesso. A differenza della revoca, rimuove del tutto il record e la pagina pubblica della credenziale restituirà 404. Usalo per errori veri (es. emissione alla persona sbagliata); per le credenziali reali preferisci la revoca, così l'assertion resta verificabile come revocata. Non viene rimborsato alcun credito.

DELETE /awards/{awardId}

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
awardId	string	Sì	L'ID dell'award (parametro di percorso)

Esempio

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

Risposta

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

---

Scarica il certificato PDF

Genera un certificato PDF A4 pronto per la stampa per una credenziale.

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

Non richiede autenticazione — questo endpoint è pubblico, così i destinatari possono scaricare il proprio certificato.

Esempio

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

La risposta è il PDF binario con l'header Content-Type: application/pdf.

---

Traccia evento della credenziale

Registra un evento di coinvolgimento. Usato dalla pagina pubblica della credenziale per popolare le statistiche di coinvolgimento. Non richiede autenticazione.

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

Parametri

Questo endpoint legge direttamente il proprio body (senza il wrapper parameters).

Parametro	Tipo	Obbligatorio	Descrizione
event	string	Sì	Uno tra view, share, download, click_linkedin_addtoprofile, click_pdf, click_verify.
network	string	No	Quando event=share, il social network: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Soppressione dei duplicati per IP: lo stesso evento dallo stesso IP viene contato una sola volta ogni 24 ore.

Esempio

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

Risposta

{
  "ok": true
}

---

Ottieni le statistiche della credenziale

Recupera i contatori cumulativi di coinvolgimento di una credenziale.

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

Non richiede autenticazione.

Risposta

I contatori sono restituiti con chiave il tipo di evento grezzo. totals contiene il conteggio totale per evento; networks scompone la suddivisione per social network degli eventi che portano un network (attualmente share). Gli eventi senza attività registrata sono semplicemente assenti.

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