POST/api/auth/sso/exchange

Laatste stap van een SSO-login (SAML/OIDC): ruilt de door de callback uitgegeven eenmalige code in voor een regulier sessie-JWT.

De pagina „POST /api/auth/sso/exchange — API-referentie” behandelt het in de URL aangeduide functiegebied. De bestaande inhoud wordt aangevuld met het daadwerkelijke verloop, de vereisten en de bekende beperkingen. Zentor beschikt niet over een API-sleutelsysteem voor ontwikkelaars. Voor het dashboard worden sessie-JWT's met een looptijd van twaalf uur en refresh-tokens met een looptijd van zeven dagen gebruikt; TOTP en SSO zijn optioneel. Widget-embed-tokens worden eenmalig als platte tekst weergegeven en zijn gebonden aan toegestane origins. De documentatie voor `POST /api/auth/sso/exchange` moet als bindende technische beschrijving van dit specifieke endpoint worden gelezen. Doorslaggevend zijn methode, pad, authenticatie, verplichte velden, mogelijke fouten en de vraag of een herhaalde aanroep hetzelfde effect heeft. Deze hulpsectie https://zentor-app.de/hilfe/api-referenz/auth/auth.sso_exchange mag daarom geen algemene reclameclaims bevatten, maar alleen daaropvolgende, navolgbare integratiestappen en onderbouwde antwoordvoorbeelden. Voor een aanroep van `/api/auth/sso/exchange` wordt de aanvraag opgebouwd volgens het register. Openbare routes vereisen geen algemene API-sleutel voor ontwikkelaars, omdat Zentor geen dergelijk sleutelsysteem aanbiedt. Beschermde widget-routes gebruiken daarentegen het eenmalig weergegeven embed-token en een origin-controle. De HTTP-status en de JSON-inhoud moeten samen worden geëvalueerd; een `ok`-veld alleen vervangt geen foutafhandeling. Bij het testen van `POST /api/auth/sso/exchange` moeten geanonimiseerde waarden worden gebruikt. Echte klantgegevens, productie-UUID's, sessietokens en concrete tijdstempels horen niet in openbare voorbeelden. De bekende platformbrede limiet bedraagt 2.000 aanvragen binnen 15 minuten; een afwijkende afzonderlijke limiet is niet onderbouwd. Niet-idempotente POST-aanroepen mogen na een onduidelijke netwerkonderbreking niet blindelings worden herhaald. Typische integratiefouten voor deze route ontstaan door ontbrekende verplichte parameters, onjuiste datatypes, verlopen eenmalige codes, niet-toegestane origins of een niet-geïmplementeerde dataset. De applicatie moet dergelijke gevallen afzonderlijk afhandelen en de door het endpoint teruggegeven foutmelding loggen, zonder geheime inhoud mee te loggen. Een geslaagde request bevestigt alleen deze verwerkingsstap, niet automatisch een daaropvolgend succes bij e-mail, betaling of SSO. Dit is voor „POST /api/auth/sso/exchange” direct relevant. De technische controle van deze pagina moet verplicht steunen op het register onder `app/frontend/src/content/api-reference/` en de bijbehorende backend-routes. Live-testvermeldingen mogen alleen beweren wat daadwerkelijk is gecontroleerd. Een negatieve test of een code-analogie is geen volledig bewijs van succes. Voor POST /api/auth/sso/exchange — API-referentie moet daarom duidelijk onderscheid worden gemaakt tussen gedocumenteerde structuur, geautomatiseerde test en zeker waargenomen livegedrag.

{"code":"<eenmalige code uit de SSO-callback-redirect>"}

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