API Omniscol — token di autenticazione

Chiave e token: due oggetti distinti

Omniscol distingue due oggetti che non vanno confusi.

Una chiave è un oggetto persistente, conservato lato Omniscol. Riunisce:

• un identificativo corto, generato casualmente, pubblico: è quello che la lista mostra, e che viaggia in ogni token per designare la chiave da verificare;
• un'etichetta descrittiva, modificabile in qualsiasi momento;
• una data di scadenza facoltativa, modificabile in qualsiasi momento;
• un segreto casuale lungo, estratto lato server, che funge da chiave di firma crittografica.

L'identificativo, l'etichetta e la data di scadenza sono informazioni di amministrazione: l'identificativo è solo un riferimento pubblico, non un elemento segreto. Il segreto, invece, è l'unico materiale di firma: generato casualmente alla creazione della chiave, resta lato server, non è modificabile, e non viene mai mostrato né restituito — né alla creazione, né nella lista delle chiavi. E anche se trapelasse, non basterebbe a forgiare un token: la firma lo combina con un sale proprio del conto e con un segreto server che, anch'essi, non lasciano mai Omniscol.

Un token è un JWT (JSON Web Token) autonomo, firmato con il segreto della chiave. È quello che trasmette al sistema esterno. Il suo contenuto firmato porta il conto interessato, la lista degli endpoint autorizzati, la chiave da cui deriva e la sua stessa data di scadenza.

In altre parole: una chiave firma, un token è firmato. Una stessa chiave può firmare più token — tutti verificabili con lo stesso segreto, quindi tutti revocati insieme se la chiave scompare.

Omniscol non memorizza il token: lo genera, lo mostra una volta, poi lo riverifica a ogni chiamata ricostituendo la sua firma a partire dal segreto della chiave (HMAC SHA-256). Nessuna autorizzazione portata dal token può quindi essere alterata senza quel segreto.

Creare un token

La schermata Condivisione è disponibile in Amministrazione → Importare/Esportare sui conti Premium. La creazione avviene in due tempi: si crea prima una chiave, poi si genera un token a partire da quella chiave.

1. Creare una chiave — inserisca un'etichetta esplicita e, se l'accesso è temporaneo, una data di scadenza. La sua etichetta e la sua scadenza restano modificabili in seguito; il suo segreto di firma, no.
2. Generare un token — selezioni la chiave, spunti gli endpoint autorizzati, scelga eventualmente una data di scadenza propria del token, poi generi il JWT.

Alla generazione, Omniscol mostra il token una sola volta. Lo copi immediatamente in un gestore di segreti: non sarà più mostrato. La scadenza del token è iscritta nel suo contenuto firmato: non si modifica a posteriori. Per cambiare questa data, generi un nuovo token.

Ci sono quindi due livelli di scadenza, indipendenti l'uno dall'altro:

• scadenza della chiave — modificabile dalla lista delle chiavi; quando viene raggiunta, tutti i token derivati da quella chiave sono rifiutati (la chiamata fallisce con un 401);
• scadenza del token — fissata alla generazione, iscritta nel JWT, e non modificabile in seguito.

Endpoint autorizzati

Un token dà accesso solo agli endpoint spuntati alla sua generazione: non presuma mai che copra tutta l'API. La lista autorizzata è trasportata nel token e verificata a ogni chiamata; una chiamata verso un endpoint non autorizzato è rifiutata (401).

Oltre agli endpoint individuali, la lista di selezione propone delle scorciatoie per modulo:

• la voce di un modulo da sola autorizza tutti i suoi endpoint;
• le varianti per operazione — lettura, modifica, creazione, eliminazione — restringono il modulo a un solo tipo di chiamata.

Spuntare «Orario [lettura]» concede così tutta la lettura degli orari senza aprire alcuna scrittura, senza spuntare ogni endpoint uno per uno. Resti al minimo indispensabile: conceda solo i moduli e le operazioni strettamente necessari all'integrazione.

Utilizzare un token

Due modi consueti per inviare il token all'API:

• Intestazione HTTP: Authorization: Bearer <token> (raccomandato).
• Query string: ?auth=<token> (pratico per il debug, ma appare nei log HTTP — da evitare in produzione).

Esempio curl, da adattare con un endpoint reale tratto dall'OpenAPI:

curl -H "Authorization: Bearer $TOKEN" \
  https://vostra-scuola.omniscol.com/api/<modulo>/<endpoint>

Documentazione OpenAPI

La schermata Importare/Esportare mostra un link OpenAPI 3.1 che apre la specifica disponibile per il conto in Swagger Editor. Vi troverà:

• la lista degli endpoint API esposti,
• gli schemi dei dati scambiati,
• i metodi e i parametri,
• le risposte attese.

La specifica è anche servita direttamente dal Suo conto, senza autenticazione:

• /api/guest/openapi.json — specifica in formato JSON;
• /api/guest/openapi.yaml (o /api/guest/openapi?yaml=true) — stesso contenuto in formato YAML;
• /api/guest/school_schema.json — schema JSON dei dati del conto.

Revocare un accesso

La revoca avviene a livello della chiave, non del singolo token.

La schermata elenca le chiavi che sono servite a generare token. Eliminare una chiave cancella il suo segreto di firma lato Omniscol: da quel momento, nessuna firma derivata da quel segreto può più essere verificata, e ogni chiamata che presenti un token proveniente da quella chiave fallisce con un 401. È l'assenza del segreto a invalidare i token, non una lista di revoca.

Per il servizio informatico, due conseguenze:

• Non c'è revoca token per token. Omniscol non conserva i JWT emessi e non può disattivarne uno isolatamente: un token già generato resta valido fino alla sua stessa scadenza, o finché la sua chiave non venga eliminata o scada.
• Modificare la scadenza di una chiave agisce immediatamente su tutti i suoi token: anticipare questa data taglia l'accesso all'insieme dei token provenienti dalla chiave.

Buona pratica: elimini senza attendere ogni chiave di cui sospetti la fuga, poi ricrei una chiave di sostituzione con un'etichetta esplicita.

Una chiave per destinazione e per uso

Poiché la revoca è per chiave, dedichi una chiave a ogni integrazione (un software esterno = una chiave). Il segreto di una chiave firma solo i suoi propri token: eliminare quella chiave invalida solo gli accessi dell'integrazione interessata, senza toccare gli altri.

Al contrario, una chiave unica condivisa tra più sistemi rende ogni revoca brutale: eliminare la chiave compromessa taglia in un colpo tutti i sistemi che se ne servivano.

Per quali integrazioni

L'API è tipicamente utilizzata per:

• sistemi di signage personalizzati (oltre ai pannelli informativi Omniscol nativi; vedi Personalizzazione dei pannelli),
• dashboard esterne che consolidano Omniscol e altre fonti,
• connettori o sincronizzazioni con un ERP o un sistema informativo operativo,
• agenti IA compatibili MCP che consumano Omniscol tramite il server MCP; vedi MCP — collegare un agente IA esterno.

Per un accesso delegato a un servizio terzo identificato (token con perimetro, consenso dell'utente, revocabile disattivando il client), preferisca il server OAuth2 di Omniscol: vedi OAuth2 / OIDC (provider).