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, the subdomain or TSSD that’s 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 | Description |
|---|---|---|
grant_type | string | Required. The type of grant. For web apps and public apps, set this property to authorization_code. |
code | string | Required. The authorization code obtained from the request to the v2/authorize endpoint. |
client_id | string | Required. The client ID issued when you create the API integration in Installed Packages. |
client_secret | string | Required for web apps. The client secret issued when you create the API integration in Installed Packages. |
redirect_uri | string | Required. The redirect address. This value must match the redirect URL that was used to request the authorization code. Don’t URL-encode the address for this request. |
scope | string | A space-separated list of data-access permissions for your application. See REST API Permission IDs and Scopes for a list of permissions. The list you specify must exactly match 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 | The member ID (MID) of the target business unit. Include this property when your use case requires you to switch between business units. |
After the request is successfully validated, the authorization service issues an access token and a refresh token. You can use the tokens returned from the v2/token endpoint only with marketingcloudapis.com endpoints. Always keep your access token secret.
| 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 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.
The body of a refresh request contains the properties in this table.
| Name | Type | Description |
|---|---|---|
grant_type | string | Required. The type of grant. When you request a refresh token, specify refresh_token for this property. |
client_id | string | Required. The client ID issued when you create the API integration in Installed Packages. |
client_secret | string | Required for web apps. The client secret issued when you create the API integration in Installed Packages. |
refresh_token | string | Required. The refresh token that was returned in the previous token request. |
scope | string | A space-separated list of data-access permissions for your application. See REST API Permission IDs and Scopes for a list of permissions. The list you specify must exactly match 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 | The member ID (MID) of the target business unit. Include this property when your use case requires you to switch between business units. |
This sample request shows how to request a refresh token.