Dynamic Keys
This guide will cover using Descope's dynamic keys within Descope flows, conditions, messaging templates, etc. Dynamic keys in Descope hold values of attributes regarding the user, device, etc., which users can utilize for various authentication flows. Dynamic keys can be used within Descope conditions, actions, connectors, etc.
Usage
- Dynamic keys 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 with values for respective keys to create conditional statements.
- You can also use these values to display to the user within the Descope flow screens.
Default Dynamic Keys
Dynamic Keys in Descope belong to a few categories.
User and unauthUser
The user and unauthUser keys load the details of an authenticated user (user) or an
unauthenticated user (unauthUser) during the flow execution. The user keys guide
provides detailed documentation of these keys.
AuthInfo
authInfo: Keys prefixed withauthInfoprovide 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 keys in a flow condition:
Device
device: Key prefixed withdevicegive 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 keys in a flow condition:
Form
form: Keys prefixed withformare 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 keys in a flow condition:
RiskInfo
riskInfo: Keys prefixed withriskInfoare specifically used for risked based authentication.
| 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.vpnDetected | Indication of whether the end user is using a VPN |
riskInfo.newDevice | Indication of whether the end user is using a device that hasn't been spotted before in your application |
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 keys in a flow condition:
Note
For more use cases on using riskInfo key, refer here
UserAgent
userAgent: Keys prefixed withuserAgentprovide 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 keys in a flow condition:
jwtClaims
jwtClaims: Keys prefixed withjwtClaimsprovide post-authentication details that are stored in the JWT response. Please note that these keys 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 keys 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 keys in a flow condition:
Additional Context Keys
In addition to the default dynamic keys mentioned above, Descope supports keys created by connectors or scriptlets used in flows.
For more information on these, please refer to the following links :
- Scriptlets : Keys as a result of executing scriptlets in flows are in the format
scripts.scriptletResult.xyzwherexyzis 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 Dynamic Keys is continually expanding, but the guide above provides a solid foundation for understanding how they are used in Descope.