The Salesforce Developers website will undergo maintenance on May 29, 2024 from 3:00 a.m. UTC to 10:00 a.m. UTC. The maintenance process may affect the availability of our documentation. Please plan accordingly.

Explanation of the Decoded JWT

After you decode the JWT, the JSON request body resembles this example.

For multi-tenant applications, such as apps on AppExchange, the authEndpoint and apiEndpointBase values are the endpoints for the current tenant.

JSON ElementDescription
expThe exp (expiration time) claim identifies the expiration time on or after which the token MUST NOT be accepted for processing. Contains an IntDate value in UTC.
request.claimsVersionThe version of the JWT claims structure. Possible values are 1 (legacy version) or 2 (default version for all new apps).
request.rest.authEndpointContains the request token URL for the environment or region. For multi-tenant applications, it can contain a tenant-specific endpoint. For example, https://YOUR_TSD.auth.marketingcloudapis.com/v1/requestToken
request.rest.apiEndpointBaseContains the base URL for REST API. For multi-tenant applications, it can contain a tenant-specific endpoint. For example, https://YOUR_TSD.rest.marketingcloudapis.com/
request.rest.refreshTokenAn OAuth refresh token for getting an updated access token. The refreshToken is valid for up to 700 days or until it has been used. If the token expires, inform the user to log out and log back in. This process generates a new refresh token for your app. If the refreshToken was used previously, you receive a 401 Unauthorized. The refreshToken has a 5-minute revocation period after use, allowing for more attempts in case the auth service doesn't respond immediately. If your package doesn't have an API Integration component, you don't receive a refreshToken.
request.user.idThe user ID.
request.user.oauthTokenThis field isn't used in claims version 2. An OAuth token that can access REST Services for the user. The token is valid for 1 hour. For more information, see Get an Access Token.
request.user.internalOauthTokenThis field isn't used in claims version 2. An OAuth token that can access SOAP API. It’s also referred to as the legacyToken.
request.user.refreshTokenThis field isn't used in claims version 2. An OAuth refresh token for getting an updated oauthToken. Refresh tokens expire after 700 days or after they’ve been used. When the token expires, inform the user to log out and log back in. This process generates a new refresh token for your app.
request.user.expiresInThis field isn't used in claims version 2. Length in seconds before the token expires. A value of 1200 is equal to 20 minutes, for example.
request.user.emailThe email address of the user.
request.user.cultureThe culture code of the user.
request.user.timezone.longNameThe friendly name of the user's timezone.
request.user.timezone.shortNameThe timezone code of the user.
request.user.timezone.offsetThe Greenwich Mean Time (GMT) offset.
request.user.timezone.dstIs Daylight Savings Time (DST) applied to this timezone setting?
request.organization.idThe account ID. For agency sub-accounts, this ID is the agency client ID and must match the value for the enterprise ID. For enterprise sub-accounts, ID this is the sub-account ID and can be different from the enterprise ID.
request.organization.enterpriseIdThe top-level enterprise account ID. For agency sub-accounts, use the agency client ID for the enterprise ID.
request.organization.dataContextThe data context value represents the edition of the account. Possible values are core (Marketing Cloud Engagement Core or Advanced Edition), reseller (Marketing Cloud Engagement Agency or Agency Client), tiered (Marketing Cloud Engagement Enterprise Edition), and enterprise (Marketing Cloud Engagement Enterprise 2.0 Edition)
request.organization.stackKeyThe server instance that the account is on. Usual production values are S1, S4, S6, S7, S10, or S50. Used when making Email SOAP API calls to set the appropriate web service end point.
request.organization.regionThe currently supported data center regions are NA1 and EU1.
request.application.idThe package ID of your application. This value is in the installed package details.
request.application.customerEnvironmentDistinguishes between production and development environments.
request.application.redirectUrlThe URL you set for the home page of your application in the installed package. This URL is where you forward the user upon successful completion of SSO through your login page.
request.application.featuresNot used.
request.application.userPermissionsNot used.

Be aware of these restrictions in your implementation code when using the refreshToken to refresh the OauthToken (access token) that is about to expire and keep it contextualized to the logged-in user:

  • The app must be installed in the account you use to log in. If logging in via Marketing Cloud Engagement and selecting the app from the AppExchange listings, the app is installed in the correct account.

  • Only use the refreshToken parameter in the request body if you need a new contextualized token.

  • Each time you get a new access token, include a request to GET /platform/v1/endpoints. This request ensures that your app is calling the correct customer endpoints.

  • If you’re using the scope parameter (retired) while requesting a new access token and you want to contextualize the access token to the logged in user, the internalOauthToken you're using MUST NOT be expired. (The expiration time is denoted in the JWT.request.user.expiresIn value, which is in seconds.)

  • Here’s an example /requestToken request body structure to follow.

When you use this structure to receive a new access token, you also receive a new refreshToken. This newly provided refreshToken must be used in the subsequent call to get a new access token. The previous refreshToken provided in the JWT is now invalid because you’ve used it.