POST/api/auth/sso/exchange

Final step of an SSO login (SAML/OIDC): exchanges the one-time code from the redirect for an access token and a refresh token.

After sign-in at the identity provider, Zentor App redirects the browser back with a one-time code in the query parameter `sso_code`. Send this code in the `code` field. The response contains `token` and `refreshToken`, as with a regular login. Each code is valid only once and only for a short time. A code that has already been used, has expired or is invalid results in 400 `SSO_EXCHANGE_INVALID`; the user then starts the SSO login again. The call is therefore not idempotent.

Overview

Call: POST /api/auth/sso/exchange. This endpoint belongs to the “Authentication” group of the Zentor App API. It is publicly accessible and requires no authentication. The call is not idempotent: every successful call triggers the action again. Required parameters: code (body). Documented error cases: 400 SSO_EXCHANGE_INVALID. The example response below shows the structure of a successful JSON response.

Auth & Security

No authentication required

Idempotent: No

Parameters

code(body, string, required)— One-time code from the SSO redirect

Example Request

{"code":"<one-time code from the SSO callback redirect>"}

Example Response

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

Error Codes

400 SSO_EXCHANGE_INVALID — The code is invalid, already used or expired.

Verified behaviour

An invalid code returns 400 `SSO_EXCHANGE_INVALID`. The success case requires a complete sign-in at the configured identity provider.

Authentication

Related articles

← Authentication