Autenticazione

Tutte le richieste alle API di badges.ninja richiedono autenticazione. Questa pagina spiega come autenticare le tue chiamate.

URL di base

https://api.badges.ninja

Tutti gli endpoint sono relativi a questo URL.

Autenticazione con chiave API

Il metodo principale di autenticazione è una chiave API trasmessa nell'intestazione X-Api-Key.

Ottenere una chiave API

Dal pannello:

1. Accedi su badges.ninja.
2. Vai su Chiavi API nella barra laterale.
3. Premi Crea chiave API.
4. Copia la chiave (viene mostrata una sola volta).

Dalla API:

Le chiavi API possono essere gestite anche via API utilizzando il tuo token JWT ottenuto dal flusso di autenticazione Cognito. Per l'approccio più semplice, usa il pannello.

Utilizzare la tua chiave API

Inserisci l'intestazione X-Api-Key in ogni richiesta:

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

Formato della chiave API

Le chiavi utilizzano il prefisso bws_:

bws_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

Formato delle richieste

• Le richieste GET trasmettono i parametri come query string
• Le richieste POST e PUT inviano un corpo JSON con un oggetto parameters
• Tutte le risposte restituiscono JSON con Content-Type: application/json

Struttura della richiesta POST/PUT

{
  "parameters": {
    "name": "My Badge",
    "description": "A sample badge"
  }
}

Richiesta d'esempio

curl -X POST https://api.badges.ninja/issuers \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "name": "My Organization",
      "url": "https://example.com",
      "email": "admin@example.com"
    }
  }'

Risposta d'esempio

{
  "statusCode": 200,
  "info": {
    "issuerId": "https://api.badges.ninja/certify-badge/issuer/abc123-def456"
  }
}

Limiti di frequenza

Le richieste API sono soggette a limiti di frequenza. Se superi il limite, riceverai una risposta 429 Too Many Requests. Attendi qualche secondo e riprova.

Endpoint pubblici

Alcuni endpoint non richiedono autenticazione. Sono gli endpoint pubblici di verifica sotto /certify-badge/ che consentono a chiunque di verificare le credenziali.