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

Authorization

Descope Project ID
AuthorizationBearer <token>

Project ID as bearer token.

In: header

Query Parameters

tenant?string
redirectUrl?string
prompt?array<string>
string
test?boolean
forceAuthn?boolean
loginHint?string
initiatedEmail?string

Request Body

application/json

stepup?boolean
Defaultfalse
customClaims?object

Custom claims to include in the JWT as key-value pairs. Keys must be strings; values can be strings, numbers, or booleans.

Example{ "claim-name": "claim-value" }
mfa?boolean
Defaultfalse
ssoAppId?string
templateOptions?object
locale?string
pkceChallenge?string

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

Formatbytes
revokeOtherSessions?boolean
revokeOtherSessionsTypes?array<string>
string

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.
curl -X POST "https://api.descope.com/v1/auth/sso/authorize" \  -H "Content-Type: application/json" \  -d '{}'
{  "url": "string"}
export interface Response {url?: string}
Was this helpful?
SparklesAsk AI about this pageArrowRight

SAML SSO API Overview

Use the Descope REST API to add SAML single sign-on (SSO) for your application.

Exchange SSO Code POST

### 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](/api/oauth/sign-up-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](/api/overview#the-user-object) for further details on how to identify users and their contact information such as email addresses and phone number.