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 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 isn’t logged in to Marketing Cloud.
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 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.
| 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. |