Token API

• Che cos’è un token API?
• Requisiti
• Dove trovo i token API?
• Creare un token
• Il token viene mostrato una sola volta
• Che cosa mostra l’elenco dei token
• Revocare un token
• Usare il token

Che cos’è un token API?

Con l’API REST di Klubraum i tuoi script, il sito web della tua associazione o altri strumenti possono lavorare con gli eventi del calendario e con i membri della tua associazione. Ogni richiesta si identifica con un token di accesso personale che crei nell’app Klubraum.

Un token di questo tipo appartiene sempre a un solo Klubraum e alla persona che lo ha creato. Ha soltanto gli ambiti che gli assegni, può scadere e puoi revocarlo in qualsiasi momento. Soprattutto, un token non può mai fare più di quanto puoi fare tu: a ogni richiesta vengono verificate anche le tue autorizzazioni attuali nell’app. Se perdi un’autorizzazione, la perde anche il token.

Requisiti

• Sei amministratore del Klubraum. Gli altri membri non vedono questa funzione.
• La tua associazione ha un piano adeguato: l’elenco dei membri, gli inviti e la rimozione dei membri sono inclusi in Plus, ogni altro endpoint richiede Pro. Senza un piano adeguato, toccando il riquadro compare un avviso per passare a un piano superiore.

Dove trovo i token API?

Apri le Impostazioni e vai su Klubraum attuale. Il secondo riquadro si chiama Token API, con il sottotitolo Token di accesso personali per l’API di Klubraum, subito sotto il riquadro per cambiare il nome dell’associazione.

Attenzione: il riquadro immediatamente sotto riguarda il token per le richieste di adesione. È un token diverso, pensato solo per il modulo di adesione sul sito della tua associazione: trovi tutti i dettagli in Richiesta di adesione sul sito dell’associazione.

Creare un token

Tocca il + in alto a destra (Crea token). La finestra Crea token API ti chiede tre cose.

Nome

Testo libero, massimo 100 caratteri, per esempio “Sincronizzazione sito web”. Assegna a ogni strumento un token proprio e chiamalo come lo strumento: così più avanti saprai con certezza quale token puoi revocare.

Ambiti

Qui stabilisci che cosa può fare il token. Gli ambiti sono quattro:

• members:read – leggere l’elenco dei membri.
• members:write – invitare e rimuovere membri.
• events:read – leggere gli eventi del calendario.
• events:write – creare, modificare, annullare ed eliminare gli eventi del calendario.

Un ambito di scrittura comprende sempre anche il corrispondente ambito di lettura. Non appena selezioni members:write, viene selezionato automaticamente anche members:read e non è più possibile deselezionarlo; sul token viene poi salvato solo l’ambito di scrittura. Lo stesso vale per events:write e events:read. È necessario almeno un ambito.

Suggerimento: scegli il minor numero possibile di ambiti. A uno script che mostra i vostri eventi solo sul vostro sito web basta events:read.

Scade dopo

Scegli 30, 90, 180 o 365 giorni – oppure Mai. Con Mai compare un avviso, e a ragione: un token senza data di scadenza resta valido finché qualcuno non lo revoca. Quando puoi, dai quindi al token una durata limitata.

Tocca poi Crea.

Il token viene mostrato una sola volta

Subito dopo la creazione l’app ti mostra il token completo: la lunga stringa segreta che inizia con klubraum_pat_. Copiala con l’apposito pulsante e salvala subito dove il tuo script o strumento la legge, preferibilmente in un gestore di password o in un archivio di segreti.

Importante: questo è l’unico momento in cui la stringa segreta è visibile. Non è più recuperabile in seguito, nemmeno da noi. Se la perdi, revoca il token e creane uno nuovo.

Non mettere mai la stringa segreta in un luogo pubblico: né nel JavaScript del vostro sito web, né in un repository pubblico, né in una conversazione dell’associazione. Chi la possiede può usare l’API esattamente con gli ambiti che hai assegnato al token.

Che cosa mostra l’elenco dei token

Nella schermata vedi tutti i token del tuo Klubraum. Per ciascuno trovi:

• il nome che gli hai dato,
• un breve prefisso che inizia con klubraum_pat_ e identifica il token senza rivelare la stringa segreta,
• gli ambiti sotto forma di chip,
• quando è stato creato, quando scade e quando è stato usato l’ultima volta.

Dalla data dell’ultimo utilizzo riconosci facilmente i token che non servono più a nessuno. I token revocati restano nell’elenco e vengono mostrati barrati.

Revocare un token

Tocca l’icona di eliminazione sul token (Revoca token) e conferma con Sì, revoca. La revoca ha effetto immediato: da quel momento ogni richiesta effettuata con questo token viene rifiutata. L’operazione non può essere annullata: un token revocato non può essere riattivato.

Suggerimento: vuoi sostituire un token ancora in uso? Crea prima il nuovo token, fai passare a esso il tuo script o strumento e solo dopo revoca quello vecchio.

Usare il token

Invia il token a ogni richiesta come bearer token nell’intestazione Authorization:

Authorization: Bearer klubraum_pat_…

Quali endpoint esistono, quali parametri si aspettano e che cosa restituiscono è descritto nella sezione per sviluppatori e nel riferimento API interattivo. In inglese.