Exchange Code | API Reference | Descope Documentation

POST

/v1/auth/oauth/exchange

Authorization

Descope Project ID

AuthorizationBearer <token>

Project ID as bearer token.

In: header

This endpoint will exchange the OAuth code 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://oauth.mycompany.com/shopping.htm?code=<unique-code\>.

Next Steps

Extract the unique code <unique-code\> from the URL parameter.
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.

{
  "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",
        "permissions": [
          "string"
        ],
        "roleIds": [
          "string"
        ]
      }
    ],
    "status": "string",
    "externalIds": [
      "string"
    ],
    "picture": "string",
    "test": false,
    "customAttributes": {
      "attribute-key": "attribute-value"
    },
    "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,
    "SCIM": true,
    "push": true,
    "permissions": [
      "string"
    ],
    "OIDC": true,
    "consentExpiration": 0,
    "recoveryEmail": "string",
    "verifiedRecoveryEmail": true,
    "recoveryPhone": "string",
    "verifiedRecoveryPhone": true,
    "modifiedTime": 0,
    "roleIds": [
      "string"
    ],
    "recoveryCodes": true
  },
  "firstSeen": true,
  "idpResponse": {
    "samlResponse": "string",
    "samlGeneratedUser": "string",
    "samlGeneratedRoles": "string",
    "oidcResponse": "string",
    "oidcGeneratedUser": "string",
    "oidcGeneratedRoles": "string",
    "idpGroups": [
      "string"
    ],
    "idpSAMLAttributes": false,
    "idpOIDCClaims": {}
  },
  "sessionExpiration": 0,
  "externalToken": "string",
  "claims": {},
  "tenantSSOID": "string",
  "trustedDeviceJwt": "string",
  "nextRefreshSeconds": 0,
  "cookieName": "string",
  "sessionCookieName": "string",
  "sessionCookieDomain": "string",
  "unsavedSSO": true
}

{  "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",        "permissions": [          "string"        ],        "roleIds": [          "string"        ]      }    ],    "status": "string",    "externalIds": [      "string"    ],    "picture": "string",    "test": false,    "customAttributes": {      "attribute-key": "attribute-value"    },    "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,    "SCIM": true,    "push": true,    "permissions": [      "string"    ],    "OIDC": true,    "consentExpiration": 0,    "recoveryEmail": "string",    "verifiedRecoveryEmail": true,    "recoveryPhone": "string",    "verifiedRecoveryPhone": true,    "modifiedTime": 0,    "roleIds": [      "string"    ],    "recoveryCodes": true  },  "firstSeen": true,  "idpResponse": {    "samlResponse": "string",    "samlGeneratedUser": "string",    "samlGeneratedRoles": "string",    "oidcResponse": "string",    "oidcGeneratedUser": "string",    "oidcGeneratedRoles": "string",    "idpGroups": [      "string"    ],    "idpSAMLAttributes": false,    "idpOIDCClaims": {}  },  "sessionExpiration": 0,  "externalToken": "string",  "claims": {},  "tenantSSOID": "string",  "trustedDeviceJwt": "string",  "nextRefreshSeconds": 0,  "cookieName": "string",  "sessionCookieName": "string",  "sessionCookieDomain": "string",  "unsavedSSO": true}

TypeScript

/**
 * NOTE: if you add a new field to this message, also add it to the OptionalJWTResponse message
 */
export interface Response {
sessionJwt?: string
refreshJwt?: string
cookieDomain?: string
cookiePath?: string
cookieMaxAge?: number
cookieExpiration?: number
user?: ResponseUser
firstSeen?: boolean
idpResponse?: IDPResponse
sessionExpiration?: number
externalToken?: string
claims?: {

}
tenantSSOID?: string
trustedDeviceJwt?: string
nextRefreshSeconds?: number
cookieName?: string
sessionCookieName?: string
sessionCookieDomain?: string
unsavedSSO?: boolean
}
export interface ResponseUser {
loginIds?: string[]
userId?: string
name?: string
email?: string
phone?: string
verifiedEmail?: boolean
verifiedPhone?: boolean
roleNames?: string[]
userTenants?: UserTenants[]
status?: string
externalIds?: string[]
picture?: string
test?: boolean
/**
 * Custom attributes as key-value pairs. Keys must be strings; values can be strings, numbers, booleans, or arrays.
 */
customAttributes?: {
[k: string]: string
}
createdTime?: number
TOTP?: boolean
SAML?: boolean
OAuth?: {
[k: string]: boolean
}
webauthn?: boolean
password?: boolean
ssoAppIds?: string[]
givenName?: string
middleName?: string
familyName?: string
editable?: boolean
SCIM?: boolean
push?: boolean
permissions?: string[]
OIDC?: boolean
consentExpiration?: number
recoveryEmail?: string
verifiedRecoveryEmail?: boolean
recoveryPhone?: string
verifiedRecoveryPhone?: boolean
modifiedTime?: number
/**
 * roleIds holds the IDs of this entry's roles. Order is NOT guaranteed to match
 *  roleNames — do not pair them by index. Use roleIds or roleNames independently.
 */
roleIds?: string[]
/**
 * whether the user has set up recovery codes
 */
recoveryCodes?: boolean
}
export interface UserTenants {
tenantId?: string
roleNames?: string[]
tenantName?: string
permissions?: string[]
/**
 * roleIds holds the IDs of this entry's roles. Order is NOT guaranteed to match
 *  roleNames — do not pair them by index. Use roleIds or roleNames independently.
 */
roleIds?: string[]
}
export interface IDPResponse {
samlResponse?: string
samlGeneratedUser?: string
samlGeneratedRoles?: string
oidcResponse?: string
oidcGeneratedUser?: string
oidcGeneratedRoles?: string
idpGroups?: string[]
idpSAMLAttributes?: boolean
idpOIDCClaims?: {

}
}

/** * NOTE: if you add a new field to this message, also add it to the OptionalJWTResponse message */export interface Response {sessionJwt?: stringrefreshJwt?: stringcookieDomain?: stringcookiePath?: stringcookieMaxAge?: numbercookieExpiration?: numberuser?: ResponseUserfirstSeen?: booleanidpResponse?: IDPResponsesessionExpiration?: numberexternalToken?: stringclaims?: {}tenantSSOID?: stringtrustedDeviceJwt?: stringnextRefreshSeconds?: numbercookieName?: stringsessionCookieName?: stringsessionCookieDomain?: stringunsavedSSO?: boolean}export interface ResponseUser {loginIds?: string[]userId?: stringname?: stringemail?: stringphone?: stringverifiedEmail?: booleanverifiedPhone?: booleanroleNames?: string[]userTenants?: UserTenants[]status?: stringexternalIds?: string[]picture?: stringtest?: boolean/** * Custom attributes as key-value pairs. Keys must be strings; values can be strings, numbers, booleans, or arrays. */customAttributes?: {[k: string]: string}createdTime?: numberTOTP?: booleanSAML?: booleanOAuth?: {[k: string]: boolean}webauthn?: booleanpassword?: booleanssoAppIds?: string[]givenName?: stringmiddleName?: stringfamilyName?: stringeditable?: booleanSCIM?: booleanpush?: booleanpermissions?: string[]OIDC?: booleanconsentExpiration?: numberrecoveryEmail?: stringverifiedRecoveryEmail?: booleanrecoveryPhone?: stringverifiedRecoveryPhone?: booleanmodifiedTime?: number/** * roleIds holds the IDs of this entry's roles. Order is NOT guaranteed to match *  roleNames — do not pair them by index. Use roleIds or roleNames independently. */roleIds?: string[]/** * whether the user has set up recovery codes */recoveryCodes?: boolean}export interface UserTenants {tenantId?: stringroleNames?: string[]tenantName?: stringpermissions?: string[]/** * roleIds holds the IDs of this entry's roles. Order is NOT guaranteed to match *  roleNames — do not pair them by index. Use roleIds or roleNames independently. */roleIds?: string[]}export interface IDPResponse {samlResponse?: stringsamlGeneratedUser?: stringsamlGeneratedRoles?: stringoidcResponse?: stringoidcGeneratedUser?: stringoidcGeneratedRoles?: stringidpGroups?: string[]idpSAMLAttributes?: booleanidpOIDCClaims?: {}}

Was this helpful?

Authorization

Request Body

Exchange OAuth code for Descope user session

Next Steps

See Also