POST/api/auth/sso/exchange

Ultimo passaggio di un login SSO (SAML/OIDC): scambia il codice monouso emesso dal callback con un normale Session JWT.

La pagina «POST /api/auth/sso/exchange — Riferimento API» descrive l'area funzionale identificata dalla URL. Il contenuto esistente viene ampliato con workflow reale, prerequisiti e limiti noti. Zentor non dispone di un sistema Developer API Key. Per il dashboard vengono usati Session JWT con durata di dodici ore e Refresh Token di sette giorni; TOTP e SSO sono opzionali. I Widget Embed Token vengono mostrati in chiaro una sola volta e sono legati alle Origin autorizzate. La documentazione di `POST /api/auth/sso/exchange` va letta come descrizione tecnica vincolante di questo endpoint specifico. Sono decisivi metodo, percorso, autenticazione, campi obbligatori, possibili errori e la questione se una nuova chiamata produca lo stesso effetto. Questa sezione https://zentor-app.de/hilfe/api-referenz/auth/auth.sso_exchange non deve contenere affermazioni pubblicitarie generiche, ma soltanto passaggi di integrazione tracciabili ed esempi di risposta comprovati. Per una chiamata a `/api/auth/sso/exchange`, la richiesta viene costruita secondo la Registry. Le route pubbliche non richiedono una Developer API Key generale perché Zentor non offre questo sistema. Le route Widget protette usano invece l'Embed Token mostrato una sola volta e una verifica Origin. Stato HTTP e contenuto JSON devono essere valutati insieme; un campo `ok` da solo non sostituisce la gestione errori. Nei test di `POST /api/auth/sso/exchange` vanno usati valori anonimizzati. Veri dati cliente, UUID produttivi, Session Token e timestamp concreti non devono comparire negli esempi pubblici. Il limite noto della piattaforma è 2.000 richieste in 15 minuti; non è dimostrato un limite individuale diverso. Le POST non idempotenti non devono essere ritentate alla cieca dopo un'interruzione di rete ambigua. Errori tipici derivano da parametri obbligatori mancanti, tipi dati errati, codici monouso scaduti, Origin non autorizzate o record non implementati. L'applicazione dovrebbe gestire separatamente tali casi e registrare il messaggio di errore restituito senza contenuti segreti. Una richiesta riuscita conferma soltanto questo passaggio, non automaticamente un successivo successo e-mail, pagamento o SSO. Questo è direttamente rilevante per `POST /api/auth/sso/exchange`. La verifica tecnica deve basarsi sulla Registry in `app/frontend/src/content/api-reference/` e sulle route Backend corrispondenti. Le note di test live possono affermare solo ciò che è stato realmente verificato. Un test negativo o un'analogia di codice non costituiscono prova completa di successo. Va quindi distinto chiaramente tra struttura documentata, test automatico e comportamento live osservato in sicurezza.

{"code":"<codice monouso dal Redirect callback SSO>"}

{"ok":true,"token":"<JWT>","refreshToken":"<Refresh-Token>"}