API ReferenceSingle Sign-On (SSO)
POST
/v1/auth/sso/exchange

Exchange SSO SAML code for Descope user session

This endpoint will exchange the unique SAML code (also called a token) for the Descope session information needed for managing the end user session. Call this endpoint from your code flow that responds to the url that was returned by the Sign-In endpoint.

The unique code \<unique-code\\> is appended as a URL parameter: code=<unique-code\>, for example, url = https://sso.mycompany.com/mywork.htm?code=<unique-code\>.

Next Steps

  1. Extract the unique code <unique-code\> from the URL parameter.
  2. Call this endpoint, passing the <unique-code\> as the request parameter

The response object includes the session JWT (sessionJwt) and refresh JWT (refreshJwt) when this endpoint completes successfully.

See Also

  • See The User Object for further details on how to identify users and their contact information such as email addresses and phone number.

Endpoint Authentication

Use authorization bearer header with the following format:

Authorization: Bearer <Project ID>

Try it

/v1/auth/sso/exchange

The Authorization access token

Authorization

Authorization
Required
Bearer <token>

In: header

Request Body

codestring

Status codeDescription
200OK
curl -X POST "https://api.descope.com/v1/auth/sso/exchange" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <Project ID>" \
  -d '{
  "code": "string"
}'

{
  "sessionJwt": "string",
  "refreshJwt": "string",
  "cookieDomain": "string",
  "cookiePath": "string",
  "cookieMaxAge": 0,
  "cookieExpiration": 0,
  "user": {
    "loginIds": [
      "string"
    ],
    "userId": "string",
    "name": "string",
    "email": "string",
    "phone": "string",
    "verifiedEmail": true,
    "verifiedPhone": true,
    "roleNames": [
      "string"
    ],
    "userTenants": [
      {
        "tenantId": "string",
        "roleNames": [
          "string"
        ],
        "tenantName": "string"
      }
    ],
    "status": "string",
    "externalIds": [
      "string"
    ],
    "picture": "string",
    "test": false,
    "customAttributes": {},
    "createdTime": 0,
    "TOTP": false,
    "SAML": false,
    "OAuth": {
      "property1": false,
      "property2": false
    },
    "webauthn": true,
    "password": true,
    "ssoAppIds": [
      "string"
    ],
    "givenName": "string",
    "middleName": "string",
    "familyName": "string",
    "editable": true
  },
  "firstSeen": true,
  "idpResponse": {
    "samlResponse": "string",
    "samlGeneratedUser": "string",
    "samlGeneratedRoles": "string",
    "oidcResponse": "string",
    "oidcGeneratedUser": "string",
    "oidcGeneratedRoles": "string"
  }
}

Was this helpful?

Previous

Start SSO

Next

Password Authentication API Overview