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

Authorize end user to sign-in using SAML SSO

Initiate a SAML SSO (Single Sign-On, "sign-in" in Descope terminology) process for an end user. Descope will coordinate the sign-in process with the service provider. Specify the URL you want to redirect the end user to after a successful sign-in in the redirectURL parameter.

When the SSO sign-in completes successfully, the endpoint returns a URL url that has a unique code \<unique-code\\>, also called a token) appended as a URL parameter to the redirectURL you provided. For example, if redirectURL = https://sso.mycompany.com/mywork.htm then url = https://sso.mycompany.com/mywork.htm?code=<unique-code\>. The unique code will be exchanged for a valid user object in the next step.

After the end user has been successfully authenticated with the identity provider (IdP) the end user session is redirected to url.

Next Steps

Call the Exchange Code endpoint from the flow that responds to the URL specified in the redirectURL field, to exchange the unique code for a user session object.

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.
  • See User Login Options for further details on the stepup, mfa, and customClaims parameters.

Endpoint Authentication

Use authorization bearer header with the following format:

Authorization: Bearer <Project ID>

Try it

/v1/auth/sso/authorize

The Authorization access token

Authorization

Authorization
Required
Bearer <token>

In: header

Request Body

stepupboolean

Default: false

customClaimsobject

mfaboolean

Default: false

ssoAppIdstring

templateOptionsobject

localestring

pkceChallengestring

relevant only for enchanted links in the point in time - other methods will ignore this field

Format: "bytes"

revokeOtherSessionsboolean

Query Parameters

tenantstring

redirectUrlstring

promptarray<string>

testboolean

Status codeDescription
200OK
curl -X POST "https://api.descope.com/v1/auth/sso/authorize?tenant=string&redirectUrl=string&prompt=%5B%0A++%22string%22%0A%5D&test=true" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <Project ID>" \
  -d '{
  "stepup": false,
  "customClaims": {},
  "mfa": false,
  "ssoAppId": "string",
  "templateOptions": {
    "property1": "string",
    "property2": "string"
  },
  "locale": "string",
  "pkceChallenge": "string",
  "revokeOtherSessions": true
}'

{
  "url": "string"
}

Was this helpful?

Previous

SAML SSO API Overview

Next

Exchange SSO Code