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.

note: 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.

JSON Parameters

Example Public App Request

Host: https://YOUR_SUBDOMAIN.auth.marketingcloudapis.com
POST /v2/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "69d8034fa6b281ffa1ed622144b66a61.a2894b8614772e68432f89ce29b66873example",
  "client_id": "2bfe9d72a4aae8f06a31025b7536be80",
  "redirect_uri": "https://127.0.0.1:80/",
  "scope": "email_read email_write email_send offline"
}

Example Web App Request

Host: https://YOUR_SUBDOMAIN.auth.marketingcloudapis.com
POST /v2/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "69d8034fa6b281ffa1ed622144b66a61.a2894b8614772e68432f89ce29b66873example",
  "client_id": "2bfe9d72a4aae8f06a31025b7536be80",
  "client_secret": "9d667c2b7fae7a329f32b6df17926154",
  "redirect_uri": "https://127.0.0.1:80/",
  "scope": "email_read email_write email_send offline"
}

Access Token Return

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.

Response Parameters

Example Web App and Public App Response

HTTP/1.1 200 OK
{
  "access_token":"9abd863f388a66e19ac4937b46448b0b.49934712976a934463e95f1e35fca2d1example",
  "refresh_token":"8d4f6f77f544019327d10023d162ac01.6c663e9a2eda319ef382d5e2b1269cb7example",
  "expires_in":1200,
  "token_type":"Bearer",
  "rest_instance_url":"mc563xyzgzs27c5t9-42k63xyzgm.rest.marketingcloudapis.com",
  "soap_instance_url":"mc563xyzgzs27c5t9-42k63xyzgm.soap.marketingcloudapis.com",
  "scope": "email_read email_write email_send offline"
}

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.

HTTP/1.1 401 Unauthorized
{
  "error": "unauthorized_client"
  "error_description": "The client is not authorized to request an authorization code using this method."
  "error_uri": "https://developer.salesforce.com/docs"
}

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.

The body of a refresh request contains the properties in this table.

This sample request shows how to request a refresh token.

POST /v2/token
Host: https://YOUR_SUBDOMAIN.auth.marketingcloudapis.com
Content-Type: application/json

{
  "grant_type": "refresh_token",
  "client_id": "2bfe9d72a4aae8f06a31025b7536be80",
  "client_secret": "9d667c2b7fae7a329f32b6df17926154",
  "refresh_token": "8d4f6f77f544019327d10023d162ac01.6c663e9a2eda319ef382d5e2b1269cb7example",
  "account_id":"12345"
}