Access Token for Web and Public App Integrations

Access Token Request

Construct an endpoint for your request by appending v2/token to the Authorization Base URL provided when you created the API integration. You can’t use legacy endpoints. After constructing the token endpoint, request an access token and refresh token by posting the authorization code to the token endpoint. The authorization code was appended to the redirect URL after the user logged in to Marketing Cloud.

By default, the tokens are revoked when the user logs out of Marketing Cloud. To create a token that isn’t revoked, first select the offline access scope for your app in Marketing Cloud Installed Packages. You must also include the offline scope in your request. This request generates access and refresh tokens that you can use, even when the user is not logged in to Marketing Cloud.

For AppExchange partners only: The subdomain, or TSSD, that is returned in the /authorize response is different from your own subdomain used as part of the /authorize request. Use the dynamic end-user subdomain returned from /authorize to construct subsequent token requests on your customer’s behalf.

JSON Parameters

NameTypeRequiredDescription
grant_typestringRequiredType of grant. Must be "authorization_code" for web apps and public apps.
codestringRequiredAuthorization code obtained as part of the v2/authorize request.
client_idstringRequiredClient ID issued when you create the API integration in Installed Packages.
client_secretstringRequiredRequired for web apps. Client secret issued when you create the API integration in Installed Packages.
redirect_uristringRequiredMust match the redirect URL used to request the authorization code. Must be in plain text as it is in Installed Packages. It can’t be URL-encoded for this request.
scopestringnoSpace-separated list of data-access permissions for your application. Review REST API Permission IDs and Scopes for a full list of permissions. Must match the scopes or be a subset of the scopes requested as part of the authorization code request. If you don’t include the scope parameter in the request, the token is issued with the scopes specified on the API integration in Installed Packages. If you include the scope parameter and use an empty string for the values, the token is generated with no scope permissions.
account_idnumbernoAccount identifier, or MID, of the target business unit if you’re trying to switch between different business units.

Example Public App Request

Example Web App Request

Access Token Return

Upon successful validation of the request, the Marketing Cloud authorization service issues an access token and a refresh token. You can use the tokens returned from the v2/token route only with marketingcloudapis.com endpoints.

Protect the access token as you would protect user credentials.

Response Parameters

NameTypeDescription
access_tokenstringActs as a session ID that the application uses to make requests. Maximum length is 512 characters. Lifetime is 20 minutes.
refresh_tokenstringToken that can be used in the future to obtain a new access token. Maximum length is 512 characters. Default lifetime is 30 days.
expires_innumberLength of time in seconds that the access token is valid.
scopestringList of scopes available for the access token.
rest_instance_urlstringYour tenant’s REST base URL for making REST API calls.
soap_instance_urlstringYour tenant’s SOAP base URL for making SOAP API calls.

Example Web App and Public App Response

Example Error Response

Upon validation failure and for certain errors, the authorization service redirects the user's web browser to the callback URL in the redirect_uri parameter with an error code and description. The following error that doesn't redirect the user's browser: Invalid client identifier error.

Refresh Access Token

The lifetime of the access token is 20 minutes. When the access token expires, your application must use the same token endpoint and refresh token to request a new access and refresh token pair. Public apps don’t have a client secret.

Example Web App Request

JSON Parameters

NameTypeRequiredDescription
grant_typestringRequiredType of grant. Must be "refresh_token".
client_idstringRequiredClient ID issued when you create the API integration in Installed Packages.
client_secretstringRequiredRequired for web apps. Client secret issued when you create the API integration in Installed Packages.
refresh_tokenstringRequiredRefresh token provided as part of the previous token pair.
scopestringnoSpace-separated list of data-access permissions for your application. Review REST API Permission IDs and Scopes for a full list of permissions. Must match the scopes or be a subset of the scopes used in the previous refresh token request. If you don’t include the scope parameter in the request, the token is issued with the scopes scopes assigned to the refresh token. If you include the scope parameter and use an empty string for the values, the token is generated with no scope permissions.
account_idnumbernoAccount identifier of the target business unit. Used to switch between business units.