Access Token for Server-to-Server Integrations
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.
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.
| Name | Type | Required | Description |
|---|---|---|---|
| grant_type | string | Required | Type of grant. Must be "client_credentials" for server-to-server integrations. |
| client_id | string | Required | Client ID issued when you create the API integration in Installed Packages. |
| client_secret | string | Required | Client secret issued when you create the API integration in Installed Packages. |
| 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. 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. 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. |
Follow these considerations when using the API directly and doing your own OAuth token management.
- Don’t request a new access token for every API call you make—each access token is reusable, and remains valid for 20 minutes. Making two API calls for every one operation is inefficient and causes throttling.
- 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.
Marketing Cloud Engagement 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.
| Name | Type | Description |
|---|---|---|
| access_token | string | Acts as a session ID that the application uses to make requests. The maximum length is 512 characters. Lifetime is 20 minutes. |
| token_type | string | The type of token that you requested. This parameter always has the value “Bearer”. |
| expires_in | number | Length of time in seconds that the token remains valid. The value has the value 1080, representing 1,080 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. |
| scope | string | Scope 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_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. |