Chiavi API

Le chiavi API ti permettono di accedere in modo programmatico alla REST API di badges.ninja. Usale per automatizzare la creazione, il rilascio e la gestione dei badge dalle tue applicazioni.

Creare una chiave API

1. Apri la pagina API Keys dalla barra laterale.
2. Fai clic su Create API Key. Si apre un modulo inline:

3. Assegna un nome alla chiave e fai clic su Create. La chiave completa viene mostrata una sola volta in un banner verde:

4. Copia subito la chiave — la chiave completa viene mostrata una sola volta. Se la perdi, dovrai crearne una nuova. Dopo aver chiuso il banner, la dashboard mostra soltanto il prefisso della chiave (ad es. bws_a1b2c3d4...); la chiave completa resta memorizzata lato server per autenticare le tue richieste:

Ogni riga mostra anche quando la chiave è stata creata e, dopo il primo utilizzo, un timestamp last used per individuare le chiavi inutilizzate.

Ambiti di accesso

Quando crei una chiave puoi renderla di sola lettura oppure lasciarla ad accesso completo:

Ambito	Consente
Accesso completo (predefinito)	Lettura e scrittura — elencare i dati e creare, rilasciare, aggiornare o eliminare.
Sola lettura	Solo richieste GET sicure. Qualsiasi richiesta che modifica i dati (POST, PUT, PATCH, DELETE) viene rifiutata con 403 Forbidden.

Usa una chiave di sola lettura per le integrazioni che devono solo leggere i tuoi dati (report, dashboard, backup), così una chiave compromessa non potrà modificare nulla. Spunta Read-only key nel modulo di creazione; le chiavi di sola lettura mostrano un badge Read-only nell'elenco. Le chiavi create prima dell'introduzione degli ambiti mantengono l'accesso completo.

Formato della chiave

Le chiavi API usano il prefisso bws_ seguito da una stringa esadecimale di 32 caratteri:

bws_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

Usare le chiavi API nelle richieste

Includi la chiave API nell'header X-Api-Key di ogni richiesta API:

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

Consulta la pagina Autenticazione per tutti i dettagli sull'autenticazione API.

Limiti delle chiavi per piano

Il numero di chiavi API che puoi creare dipende dal tuo piano:

Piano	Limite di chiavi API
Free	1
Starter ($9/mo)	5
Pro ($29/mo)	20

Scadenza delle chiavi

Ogni chiave API scade un anno dopo la sua creazione. Una volta scaduta, la chiave non autentica più le richieste, esattamente come se fosse stata eliminata. Crea una nuova chiave prima che la vecchia scada per evitare interruzioni.

Eliminare una chiave

1. Apri la pagina API Keys.
2. Trova la chiave che vuoi eliminare.
3. Fai clic su Delete.
4. Conferma l'eliminazione.

Una volta eliminata, la chiave smette subito di funzionare. Le applicazioni che la usano riceveranno errori di autenticazione.