Token API

Un token API consente a un software di terze parti di chiamare i punti di accesso API di Omniscol per conto della scuola, in lettura e, se sono selezionati punti di accesso API di scrittura, in scrittura.

È potente — quindi da maneggiare con cautela.

Generazione

Un token viene generato in Condivisione (Importare/Esportare > Condivisione). Occorre fornire:

• una chiave (generata in Omniscol, con etichetta e scadenza eventuale; la sua data di scadenza può essere modificata in seguito),
• un ambito: la lista dei punti di accesso API che questo token potrà chiamare (concedere solo ciò che è strettamente necessario),
• eventualmente una scadenza del token. Questa data è iscritta nel JWT generato e non può essere modificata in seguito.

Eliminare la chiave, o raggiungerne la scadenza, revoca immediatamente i token derivati. Per cambiare la scadenza di un singolo token, generare un nuovo JWT.

Utilizzo

Il token si trasmette nell'intestazione HTTP Authorization: Bearer <token>, oppure (meno consigliato per la produzione) nell'URL tramite ?auth=<token>.

Buone pratiche

• Una chiave per integrazione — facilita la revoca indipendente.
• Ambito minimo — selezionare solo le API necessarie, non tutto per impostazione predefinita.
• Scadenza al livello giusto — usare la scadenza della chiave per gestire un'integrazione nel tempo; usare la scadenza del token per un accesso temporaneo non modificabile.
• Rotazione periodica — rigenerare la chiave ogni 6-12 mesi.
• Non in Git — il token non deve finire versionato in un repository pubblico. Usare le variabili d'ambiente del proprio server.

Differenza con OIDC / SSO

Per connettere utenti reali con la loro identità istituzionale, usare OIDC / SSO. Il token API è destinato alle integrazioni tecniche da server a server, non alla connessione quotidiana degli utenti.