Authorization Code Reference

Authorization Code Request

Your application initiates the authorization code flow by directing the end user to the v2/authorize URL. You can specify the required scopes or permissions as part of the URL. Upon successful validation, the Marketing Cloud authorization service redirects the user’s web browser to the Marketing Cloud login page.

JSON Parameters

NameTypeRequiredDescription
response_typestringRequiredType of response. Must be "code" for web apps and public apps.
client_idstringRequiredClient ID issued when you create the API integration in Installed Packages.
redirect_uristringRequiredWhere the end user is directed after login. Must match a redirect URL specified on the API integration in Installed Packages. The URL must be encoded for this request.
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 assigned to 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.
statestringnoUsed by your application to maintain state between the request and the redirect. The authorization server includes this value when redirecting the end-user’s browser back to your application. This parameter is recommended because it helps to minimize the risk of cross-site forgery attack.

Example Request URL

Authorization Code Return

After the user logs in, Marketing Cloud generates an authorization code and redirects the user’s web browser to the callback URL specified by the redirect_uri parameter. The authorization code is appended to the redirect URL.

Response Parameters

NameTypeDescription
codestringAuthorization code that must be exchanged for access tokens. Maximum length is 512 characters. Lifetime is 5 minutes.
statestringState value that you passed as part of the original request, if applicable.
tssdstring(AppExchange partners only) tssd is a dynamic value that represents the end user’s subdomain and is returned only when your customers use your app. Each of your customers has a unique tssd. Use the returned tssd to construct all subsequent requests on your customer’s behalf. To make offline requests on behalf of a customer, store this value so that you can construct requests at a later date. Ensure that your app validates tssd with the character set [a-zA-Z0-9-]. tssd is not returned in local testing.

Example URL Response

Example Error Response

Upon validation failure, the authorization service redirects the user’s web browser to the callback URL specified in the redirect_uri parameter with an error code and description.