Dynamic Values

This guide will cover using dynamic values within Descope flows, conditions, messaging templates, etc. Dynamic values in Descope hold values of attributes regarding the user, device, etc., which users can utilize for various authentication flows. Dynamic values can be used within Descope conditions, actions, connectors, etc.

Usage

Dynamic values can be specific items you may want to pass to the email or SMS for the various authentication methods as a part of custom templates. Refer to custom templates here.
These also can be utilized under conditional flows where users can check dynamic values to create conditional statements.
You can also use these values to display to the user within the Descope flow screens.

Default Dynamic Values

Dynamic Values in Descope belong to a few categories.

User

user: Keys prefixed with user are used for authenticated users.

Dynamic Key	Description
`user.userId`	A unique identifier for a user
`user.loginIds`	All unique identifiers for a user. Usually an email and/or phone
`user.name`	The user's name
`user.givenName`	The user's given name
`user.middleName`	The user's middle name
`user.familyName`	The user's family name
`user.email`	The user's email address
`user.emailDomain`	The domain of the user's email address
`user.phone`	The user's phone number
`user.verifiedEmail`	Whether the user's email address has been verified
`user.verifiedPhone`	Whether the user's phone number has been verified
`user.userTenants`	An array of tenants associated with the user
`user.picture`	The user's picture
`user.status`	The user's status including `active` , `invited` or `disabled`
`user.tenantNames`	All user tenant names as array
`user.tenantIds`	All user tenant IDs as array
`user.tenant.roles`	The tenant level user roles
`user.fingerprint.knownDevice`	Indication of whether the unauthenticated user is using a device that has been spotted before in your application
`user.test`	Will be set to true if this user is a test user
`user.lastAuth.country`	Last country user logged in from
`user.lastAuth.countries`	Latest countries user logged in from
`user.lastAuth.city`	Last city user logged in from
`user.lastAuth.cities`	Latest cities user logged in from
`user.lastAuth.ip`	Last IP user logged in from
`user.lastAuth.ips`	Latest IPs user logged in from
`user.lastAuth.time`	Last time user logged in
`user.password`	Indicates whether the user has ever logged in with a password
`user.totp`	Indicates whether user has TOTP set
`user.project.roles`	All project level roles associated with this user
`user.project.permissions`	All project level permissions associated with this user
`user.saml`	Indicates whether the user has ever logged in with SAML
`user.webauthn`	Indicates whether the user has ever logged in with Passkeys (Webauthn)
`user.loggedIn`	Indicates whether the user is already logged in
`user.customAttributes.<attribute-name>`	The custom attribute for the user

Example of utilizing user Dynamic keys in a flow condition:

UnauthUser

Descope allows you to load data for both authenticated and unauthenticated users. When a user first supplies their login ID (email, phone number, custom login ID, etc.) but has not completed authentication, you can load their details within your flow using the unauthUser dynamic keys.

unauthUser : Keys prefixed with unauthUser is used for unauthenticated users.

Dynamic Key	Description
`unauthUser.userId`	A unique identifier for a user
`unauthUser.loginIds`	All unique identifiers for a user. Usually an email and/or phone
`unauthUser.name`	The user's name
`unauthUser.givenName`	The user's given name
`unauthUser.middleName`	The user's middle name
`unauthUser.familyName`	The user's family name
`unauthUser.email`	The user's email address
`unauthUser.emailDomain`	The domain of the user's email address
`unauthUser.phone`	The user's phone number
`unauthUser.verifiedEmail`	Whether the user's email address has been verified
`unauthUser.verifiedPhone`	Whether the user's phone number has been verified
`unauthUser.userTenants`	An array of tenants associated with the user
`unauthUser.picture`	The user's picture
`unauthUser.status`	The user's status including `active` , `invited` or `disabled`
`unauthUser.tenantNames`	All user tenant names as array
`unauthUser.tenantIds`	All user tenant IDs as array
`unauthUser.tenant.roles`	The tenant level user roles
`unauthUser.fingerprint.knownDevice`	Indication of whether the unauthenticated user is using a device that has been spotted before in your application
`unauthUser.test`	Will be set to true if this user is a test user
`unauthUser.lastAuth.country`	Last country user logged in from
`unauthUser.lastAuth.countries`	Latest countries user logged in from
`unauthUser.lastAuth.city`	Last city user logged in from
`unauthUser.lastAuth.cities`	Latest cities user logged in from
`unauthUser.lastAuth.ip`	Last IP user logged in from
`unauthUser.lastAuth.ips`	Latest IPs user logged in from
`unauthUser.lastAuth.time`	Last time user logged in
`unauthUser.password`	Indicates whether the user has ever logged in with a password
`unauthUser.totp`	Indicates whether user has TOTP set
`unauthUser.project.roles`	All project level roles associated with this user
`unauthUser.project.permissions`	All project level permissions associated with this user
`unauthUser.saml`	Indicates whether the user has ever logged in with SAML
`unauthUser.webauthn`	Indicates whether the user has ever logged in with Passkeys (Webauthn)
`unauthUser.customAttributes.<attribute-name>`	The custom attribute for the user

Example of utilizing unauthUser Dynamic keys in a flow condition:

Example of utilizing unauthUser.lastAuth.time in a flow condition:

Using the dynamic key unauthUser.lastAuth.time, Descoper can control the behavior of the flow based on how long ago an unauthenticated user had logged in. The operator in the condition supports checking the time in terms of minutes, hours or days. This can help in use cases where user's last logged in time logic needs to be applied. A similar key is also available for check for authenticated users (user.lastAuth.time).

unauthUser Variations

By default, when using unauthUser context keys, the user is loaded by email; however, there may be scenarios where the user needs to be loaded by another variation. Descope supports loading unauthenticated users using unauthUser.byEmail (default), unauthUser.byPhone, and unauthUser.byTenant.

AuthInfo

authInfo: Values prefixed with authInfo provide authentication related information to the user.

Dynamic Key	Description
`authInfo.sessionJwt`	A JSON web token used for session authentication and authorization purposes
`authInfo.refreshJwt`	A JSON web token used for obtaining a new sessionJwt after expiration
`authInfo.cookieDomain`	The domain that the cookie is valid for, used for cross-domain authentication
`authInfo.cookiePath`	The path that the cookie is valid for, used for limiting cookie access to specific paths
`authInfo.cookieMaxAge`	The maximum duration for which the cookie is valid, in seconds
`authInfo.cookieExpiration`	The date and time at which the cookie expires, used for setting an explicit expiration date
`authInfo.firstSeen`	Whether the user is logging in for the first time

Example of utilizing authInfo Dynamic values in a flow condition:

Device

device: Values prefixed with device give information with respect to the user's device.

Dynamic Key	Description
`device.location.scheme`	The scheme of the URL where the flow is used. Such as `http` or `https`.
`device.location.uri`	The full URI where the flow is used. Such as `https://app.domain.com/path?q=v#fragment`
`device.location.hostname`	The hostname where the flow is used. Such as `app.domain.com`.
`device.location.port`	The port where the flow is used. Such as `3000`
`device.location.path`	The path where the flow is used. Such as `/path`
`device.location.rawQuery`	The raw query string where the flow is used. Such as `"q=v"`
`device.location.fragment`	The fragment (the URI part after #) where the flow is used. Such as `fragment`, in case the full URI is `https://app.domain.com#fragment`
`device.location.query`	The query object where the flow is used. Such as `{"q":"v"}`
`device.webAuthnSupport`	Indicates whether the device supports Passkeys (Webauthn)

Example of utilizing device Dynamic values in a flow condition:

Form

form: Values prefixed with form are specific to inputs provided by the user while authenticating into their application.

Dynamic Key	Description
`form.email`	The email form input
`form.emailDomain`	The domain of the email form input
`form.phone`	The phone form input
`form.photo`	The picture uploaded by the "Take Photo" component
`form.invitees`	The invitees form input
`form.externalId`	The custom login ID form input
`form.fullName`	The display name form input
`form.firstName`	The given name form input
`form.lastName`	The family name form input
`form.tenantDomain`	The tenant domain form input
`form.middleName`	The middle name form input
`form.selfProvisionDomains`	The self provision domains form input
`form.impersonateId`	The impersonate ID selected from the form input
`form.entityId`	The entity ID form input
`form.tenantName`	The tenant name form input
`form.idpCert`	The IdP certificate form input
`form.idpMetadataURL`	The IdP metadata URL form input
`form.idpURL`	The IDP URL form input
`form.displayName`	The display name form input
`form.givenName`	The given name form input
`form.familyName`	The family name form input
`form.trustThisDevice`	Mark this device as trusted

Example of utilizing form Dynamic values in a flow condition:

RiskInfo

riskInfo: Values prefixed with riskInfo are specifically used for risked based authentication.

For more details on using riskInfo key, refer here. Fraud / Risk based connectors will have their own context keys that will only show up if the connector is configured.

Dynamic Key	Description
`riskInfo.botDetected`	Indicates whether a user is likely a bot based on their behavior or activity
`riskInfo.riskScore`	A numerical value representing the risk score associated with a user's behavior or activity
`riskInfo.trustedDevice`	Indication of whether this device has been marked as trusted before or not
`riskInfo.impossibleTravel`	Indication of whether this user has connected from two different countries and the time between those connections can't be made through conventional air travel

Example of utilizing riskInfo Dynamic values in a flow condition:

Note

For more use cases on using riskInfo key, refer here

UserAgent

userAgent: Values prefixed with userAgent provide details about the system, operating system, host application etc.

Dynamic Key	Description
`userAgent.mobile`	Is request coming from a mobile device?
`userAgent.desktop`	Is request coming from a PC?
`userAgent.device`	Device type (present for iOS and Android devices)
`userAgent.raw`	Raw User Agent header
`userAgent.name`	Short agent name
`userAgent.os`	Operating system
`userAgent.osVersion`	Operating system version
`userAgent.tablet`	Is request coming from a Tablet?
`userAgent.url`	URL provided in case of a bot

Example of utilizing userAgent Dynamic values in a flow condition:

jwtClaims

jwtClaims: Values prefixed with jwtClaims provide post-authentication details that are stored in the JWT response. Please note that these values will only be available after the user goes through an authentication flow.

Dynamic Key	Description
`jwtClaims.amr`	Identifiers Used
`jwtClaims.drn`	Type of Token
`jwtClaims.exp`	Timestamp of Expiration Time
`jwtClaims.iss`	Timestamp of Issued Time
`jwtClaims.sub`	User Id

In addition to the values above, custom claims on the JWT that are Strings will also be available. They can be accessed as jwtClaims.custom-claim-key.

Example of utilizing jwtClaims Dynamic values in a flow condition:

Additional Context Keys

In addition to the default dynamic values mentioned above, Descope supports values created by connectors or scriptlets used in flows.

For more information on these, please refer to the following documents:

Scriptlets: Keys as a result of executing scriptlets in flows are in the format scripts.scriptletResult.xyz where xyz is the variable holding the result of the scriptlet action.
Connectors: Keys being returned from connectors are prefixed with connectors..
Document: Key used specifically for document being uploaded via flows.

The list of available Dynamic Values is continually expanding, but the guide above provides a solid foundation for understanding how they are used in Descope.

Was this helpful?

On this page