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 Element | Description |
|---|---|
| exp | The 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.claimsVersion | The version of the JWT claims structure. Possible values are 1 (legacy version) or 2 (default version for all new apps). |
| request.rest.authEndpoint | Contains 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.apiEndpointBase | Contains 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.refreshToken | An 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.id | The user ID. |
| request.user.oauthToken | This 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.internalOauthToken | This 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.refreshToken | This 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.expiresIn | This 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.email | The email address of the user. |
| request.user.culture | The culture code of the user. |
| request.user.timezone.longName | The friendly name of the user's timezone. |
| request.user.timezone.shortName | The timezone code of the user. |
| request.user.timezone.offset | The Greenwich Mean Time (GMT) offset. |
| request.user.timezone.dst | Is Daylight Savings Time (DST) applied to this timezone setting? |
| request.organization.id | The 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.enterpriseId | The top-level enterprise account ID. For agency sub-accounts, use the agency client ID for the enterprise ID. |
| request.organization.dataContext | The data context value represents the edition of the account. Possible values are core (Marketing Cloud Core or Advanced Edition), reseller (Marketing Cloud Agency or Agency Client), tiered (Marketing Cloud Enterprise Edition), and enterprise (Marketing Cloud Enterprise 2.0 Edition) |
| request.organization.stackKey | The 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.region | The currently supported data center regions are NA1 and EU1. |
| request.application.id | The package ID of your application. This value is in the installed package details. |
| request.application.customerEnvironment | Distinguishes between production and development environments. |
| request.application.redirectUrl | The 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.features | Not used. |
| request.application.userPermissions | Not 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
refreshTokenparameter 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.