Access Token for Server-to-Server Integrations

Access Token Request

Construct a static endpoint for your request by appending v2/token to the Authorization Base URI provided to you when you created the API integration in Installed Packages. You can’t use legacy endpoints. Request an access token by providing the client ID and secret that you received when you created the API integration in Installed Packages.

When the access token expires, your application must request a new access token using the same v2/token route as before. The lifetime of an access token is 20 minutes.

JSON Parameters

NameTypeRequiredDescription
grant_typestringRequiredType of grant. Must be "client_credentials" for server-to-server integrations.
client_idstringRequiredClient ID issued when you create the API integration in Installed Packages.
client_secretstringRequiredClient secret issued when you create the API integration in Installed Packages.
scopestringnoSpace-separated list of data-access permissions for your application. Review REST API Permission IDs and Scopes for a full list of permissions. 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. Use to switch between business units. If you don’t specify account_id, the returned access token is in the context of the business unit that created the integration.

Example Request

Important Considerations

Follow these considerations when using the API directly and doing your own OAuth token management.

  1. Do not request a new access token for every API call you make—-each access token is good for 20 minutes and is reusable. Making two API calls for every one operation is inefficient and causes throttling.
  2. Be careful where you store your client ID and secret. Never expose this information on the client side via JavaScript or store it in a mobile application. Ensure that these credentials are stored securely in your application.

Access Token Return

Marketing Cloud returns an access token. Your application must extract the access token and store it safely.

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.
token_typestringWill be “Bearer”.
expires_innumberLength of time in seconds that the token is valid: approximately 1080 seconds, or 18 minutes. The actual access token lifetime is 20 minutes, but the expires_in setting is 18 minutes because we recommend that you refresh your token two minutes before its lifetime ends.
scopestringScope values assigned to the client ID and secret pair. Returns all scopes for the integration in Installed Packages if the request doesn’t contain scopes. If scopes are included in the request, it returns these scopes, provided that the integration has these scopes in Installed Packages.
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 Response

Example Error Response