Session Overview

Descope implements the session management with two tokens to improve performance and security:

• Session Token
• Refresh Token

These tokens are implemented as JWTs (JSON Web Tokens), meaning that the information stored in the object is signed with a private key, and using the public key, any service can validate that the data was not tampered with by a malicious actor.

Your application server can validate the session token (short expiry time) without a connection to Descope service. If the application server finds the session token invalid, it calls the Descope service with the refresh token (longer expiry time) to get a new session token.

If the refresh token is invalid for some reason, such as a logout call or expiry time, then the user is forced to re-login.

Configurations for session management can be configured at a project level or tenant level. Please review the applicable guides for configuring session handling at a project or tenant level.

Descope Session JWT Structure

The Descope JWT contains standard and Descope specific claims:

• amr: (Authentication Methods References): An array of the authentication methods used:

  • oauth - OAuth was used.
  • email - OTP, Magic Link, or Enchanted Link was used through email.
  • sms - OTP or Magic Link was used through sms.
  • whatsapp - Whatsapp nOTP was used.
  • webauthn - Passkeys were used.
  • totp - Authenticator app was used.
  • fed - SSO was used.
  • pwd - Password was used.
  • mfa - The user verified with two or more unique authentication methods.

• drn: (Descope Resource Name) References where the token is stored.

• exp: (Expiration Time): Specifies the expiration time of the token, represented as a UNIX epoch timestamp.

• iat: (Issued At): The time the JWT was issued, represented as a UNIX epoch timestamp.

• iss: (Issuer): Identifies the principal that issued the JWT. Within Descope's JWT, this is the Descope project ID.

• sub: (Subject): The principal that is the subject of the JWT. Within Descope's JWT, this is the User ID of the user within Descope.

• dct: (Descope Current Tenant): Holds the value of user's active tenant. If the user is associated with a single tenant within Descope, this claim is set to that tenant value.

• tenants: A list of associated tenants (represented by unique IDs) associated with this JWT.

  • For each tenant:
    • permissions: A list of permissions granted to the subject within the context of that tenant.
    • roles: Roles associated with the subject for that specific tenant.

Below is an example of a Descope Session JWT with tenants associated to the user.

{
  "amr": [
    "email"
  ],
  "drn": "DS",
  "exp": 1692304651,
  "iat": 1692304051,
  "iss": "P2RFvFexVaxxNFK6rhP0ePtaGfTK",
  "sub": "U2RG6grrbT3REKYqk5yC4SjkMqzA",
  "tenants": {
    "T2U7vUH1NPy4JzWHruoOVIGyzYlu": {
      "permissions": [
        "AppSecEngineer",
        "Marketing",
        "Support"
      ],
      "roles": [
        "Engineering",
        "Product Manager"
      ]
    },
    "T2U7vVBqyZv6HdGtGLdnkgCbNxrC": {
      "permissions": [
        "AppSecEngineer",
        "Support"
      ],
      "roles": [
        "Support"
      ]
    }
  }
}