API ReferenceSession
POST
/v1/auth/tenant/select

Authorization

Descope Project ID:Refresh JWT
AuthorizationBearer <token>

Project ID:Refresh JWT as bearer token.

In: header

Request Body

application/json

tenant?string

Set the active tenant for the user's current session

This endpoint allows you to get a new session token and refresh token with the dct claim on the JWT which shows the active selected tenant for the user.

See Tenant Selection Article for more details of the usage.

curl -X POST "https://api.descope.com/v1/auth/tenant/select" \  -H "Content-Type: application/json" \  -d '{}'
{  "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,    "dependent": true,    "userFamilies": [      {        "familyId": "string",        "roleNames": [          "string"        ],        "permissions": [          "string"        ],        "familyScopedAttributes": {}      }    ],    "lockReason": "string",    "tempLockExpiration": 0  },  "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,  "knownDeviceJwt": "string",  "ssoAuthenticationOnly": true}
/** * 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?: {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?: booleandependent?: booleanuserFamilies?: UserFamilies[]lockReason?: stringtempLockExpiration?: number}firstSeen?: booleanidpResponse?: IDPResponsesessionExpiration?: numberexternalToken?: stringclaims?: {}tenantSSOID?: stringtrustedDeviceJwt?: stringnextRefreshSeconds?: numbercookieName?: stringsessionCookieName?: stringsessionCookieDomain?: stringunsavedSSO?: booleanknownDeviceJwt?: string/** * Set only when the login went through an SSO configuration classified authentication only: the *  person was verified, no user was created, updated or signed in, and no session was issued. *  Lets a flow branch on what kind of login it just completed. Optional so it stays absent for *  every ordinary auth response rather than adding a field nobody asked for. */ssoAuthenticationOnly?: 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 UserFamilies {familyId?: stringroleNames?: string[]permissions?: string[]familyScopedAttributes?: {}}export interface IDPResponse {samlResponse?: stringsamlGeneratedUser?: stringsamlGeneratedRoles?: stringoidcResponse?: stringoidcGeneratedUser?: stringoidcGeneratedRoles?: stringidpGroups?: string[]idpSAMLAttributes?: booleanidpOIDCClaims?: {}}
Was this helpful?

Get Session History GET

### Get user's session history This API Endpoint will return the current user's session history including geo-location and IP address. This endpoint requires the user to be signed in and have a valid `refreshJwt`. The `refreshJwt` is then used as part of the Authorization Bearer to perform this task.

Sign-Out POST

### Log the user out from the provided session This API endpoint will sign the user out of the provided session using the `refreshToken`. Successfully executing this endpoint will invalidate the provided refresh tokens. Response will also include all user tokens and fields empty, so the executing client will remove cookies as well.