Access Token for Web and Public App Integrations

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

By default, the tokens are revoked when the user signs out. To create a token that isn’t revoked, first select the offline access scope for your app in 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 isn’t logged in.

The client_id, client_secret, access_token, and instance URL values in this document are fictitious. Replace these values with the appropriate values for your own instance and account.

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.

Name	Type	Required	Description
grant_type	string	Required	Type of grant. Must be "authorization_code" for web apps and public apps.
code	string	Required	Authorization code obtained as part of the v2/authorize request.
client_id	string	Required	Client ID issued when you create the API integration in Installed Packages.
client_secret	string	Required	Required for web apps. Client secret issued when you create the API integration in Installed Packages.
redirect_uri	string	Required	Must 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.
scope	string	no	Space-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_id	number	no	Account identifier, or MID, of the target business unit if you’re trying to switch between different business units.

Upon successful validation of the request, the 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.

Name	Type	Description
access_token	string	Acts as a session ID that the application uses to make requests. Maximum length is 512 characters. Lifetime is 20 minutes.
refresh_token	string	Token that can be used in the future to obtain a new access token. Maximum length is 512 characters. Default lifetime is 30 days.
expires_in	number	Length of time in seconds that the access token is valid.
scope	string	List of scopes available for the access token.
rest_instance_url	string	Your tenant’s REST base URL for making REST API calls.
soap_instance_url	string	Your tenant’s SOAP base URL for making SOAP API calls.

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.

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.

Name	Type	Required	Description
grant_type	string	Required	Type of grant. Must be "refresh_token".
client_id	string	Required	Client ID issued when you create the API integration in Installed Packages.
client_secret	string	Required	Required for web apps. Client secret issued when you create the API integration in Installed Packages.
refresh_token	string	Required	Refresh token provided as part of the previous token pair.
scope	string	no	Space-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 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_id	number	no	Account identifier of the target business unit. Used to switch between business units.