Articles in this section

See more

API Authorization

Avatar
MemberClicks Engineering
Updated
Follow

What is it?

The MC Professional API implements the OAuth 2.0 authorization framework to control access to the protected API resources.  The MC Professional authorization server is responsible for authenticating login credentials, determining the access level, and issuing access tokens for use with the MC Professional resource server.

There are five flows available for interacting with the authorization server to obtain access tokens. These five flows are defined by the following grant types:

The main differences between the grant types are the type of login credentials required, the number of steps to obtain an access token, the resource owner interaction, and support for the refresh token.

It is the responsibility of the 3rd party client system to store the client ID and client secret and to secure the client secret.

Once the 3rd party client system has obtained an access token, it can then use the access token to make calls to the MC Professional resource servers.  The API Resources page details how to use the access token and what resources are available.

Access tokens are valid for one hour.  When an access token expires, the client can request another access token if a refresh token is available.

Refresh tokens are supported for the Authorization Code and Resource Owner Password Credentials grant types if enabled for the client.  Refresh tokens are valid for 30 days.

Authorization Process

Depending on the grant type, the authorization process for obtaining access tokens requires an authorization request/response and/or an access token request/response.  The following table lists the authorization process for each grant type:

Grant Type Authorization Request/Response Access Token Request/Response
Authorization Code Yes Yes
Implicit Yes No
Resource Owner Password Credentials No Yes
Client Credentials No Yes
Refresh Token No Yes

HTTP Basic Access Authentication

For access token requests, the client ID and client secret are encoded on the Authorization request header using HTTP Basic Access Authentication.  The following is the format of the Authorization header:

Authorization: Basic <clientCredentials>

  • clientCredentials: Base64 encoded <clientId>:<clientSecret>
  • clientId: the client ID configured in API Management for the 3rd party client
  • clientSecret: the client secret configured in API Management for the 3rd party client

Example

Using the example values below:

  • clientId: 8ZgZxV9B8rdwVXJ8lzuh
  • clientSecret: fc7bad78c5ba4cebaac0bfb973a06dc3

Base64 encoded "8ZgZxV9B8rdwVXJ8lzuh:fc7bad78c5ba4cebaac0bfb973a06dc3" becomes "OFpnWnhWOUI4cmR3VlhKOGx6dWg6ZmM3YmFkNzhjNWJhNGNlYmFhYzBiZmI5NzNhMDZkYzM=" and the following is the resulting Authorization header:

Authorization: Basic OFpnWnhWOUI4cmR3VlhKOGx6dWg6ZmM3YmFkNzhjNWJhNGNlYmFhYzBiZmI5NzNhMDZkYzM=

Authorization Code Grant Type

Overview

The Authorization Code grant type is used to obtain access tokens and refresh tokens if enabled.  

This grant type requires the interaction of the resource owner (a member of the organization) and involves redirection from the MC Professional site to the 3rd party client system.  The resource owner provides their username and password on the MC Professional site if not already logged in, and the 3rd party client system passes the client ID and client secret to the MC Professional authorization server.

Flow

With the Authorization Code grant type, the resource owner typically starts on the 3rd party client site.  To initiate the authorization process, the resource owner clicks a link to the MC Professional authorization server.  This link contains the client ID as one of the request parameters.  

  • If the resource owner is already logged in to the MC Professional site, they will be redirected immediately to the specified redirect URI.  
  • If the resource owner is not already logged in to the MC Professional site, they are taken to the login page to enter their username and password.  After successful login, they are redirected to the specified redirect URI.

The redirect URI should point to a location controlled by the 3rd party client.  MC Professional will add an authorization code to the redirect URI as a request parameter.  The authorization code is valid for 10 minutes and can only be used once.

The 3rd party client system will parse the authorization code from the redirect URI.  Then the 3rd party system will make a request to the MC Professional authorization server using the client ID, client secret and authorization code to obtain the access token and refresh token if enabled.

API_Authorization_Code_Grant_Type_Flow.svg

Authorization Request

The authorization request is an HTTP GET to the /oauth/v1/authorize endpoint.  This is typically a link that a resource owner clicks in their browser.  

The following is the format of the authorization request:

https://<orgId>.memberclicks.net/oauth/v1/authorize?response_type=code&client_id=<clientId>&scope=<scope>&state=<state>&redirect_uri=<redirectURI>

  • orgId: the MC Professional organization ID
  • clientId: the client ID configured in API Management for the 3rd party client
  • scope: the scope requested for the access token. Scope can be 'read', 'write', or 'read write'.
  • state (optional but recommended): a unique value that will be returned in the authorization response.  This value can be used by the 3rd party system to maintain state and to prevent cross-site request forgery.
  • redirectURI (required): a URL encoded redirect URI configured in API Management for the 3rd party client.  The resource owner will be redirected to this URI after successful login.

Example

Using the example values below, the following is the resulting authorization request:

  • orgId: apiexample
  • clientId: 8ZgZxV9B8rdwVXJ8lzuh
  • scope: read
  • state: 8d152e78-3df5-11e6-ac61-9e71128cae77
  • redirectURI: https://www.google.com

https://apiexample.memberclicks.net/oauth/v1/authorize?response_type=code&client_id=8ZgZxV9B8rdwVXJ8lzuh&scope=read&state=8d152e78-3df5-11e6-ac61-9e71128cae77&redirect_uri=https%3A%2F%2Fwww.google.com

Authorization Response

After successful login, the authorization response returns an HTTP status 302 Found with a location set to the redirect URI specified in the authorization request and the authorization code as a request parameter.  

The following is the format of the authorization response redirect URI:

HTTP/1.1 302 Found
Location: <redirectURI>?code=<authorizationCode>&state=<state>

  • redirectURI: the redirect URI specified in the authorization request
  • authorizationCode: the authorization code for obtaining an access token
  • state: the state if included in the authorization request

Example

The following is the authorization response from the example authorization request above:

HTTP/1.1 302 Found
Location: https://www.google.com/?code=G7bM5f&state=8d152e78-3df5-11e6-ac61-9e71128cae77

Access Token Request

The access token request is an HTTP POST to the /oauth/v1/token endpoint.  The client ID and client secret are encoded in the Authorization header using HTTP Basic Access Authentication and the authorization code is included in the POST body. 

The following is the format of the access token request:

POST /oauth/v1/token HTTP/1.1
Host: <orgId>.memberclicks.net
Authorization: Basic <clientCredentials>
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache

grant_type=authorization_code&code=<authorizationCode>&scope=read&redirect_uri=<redirectURI>

  • orgId: the MC Professional organization ID
  • clientCredentials: Base64 encoded <clientId>:<clientSecret>
  • clientId: the client ID configured in API Management for the 3rd party client
  • clientSecret: the client secret configured in API Management for the 3rd party client
  • authorizationCode: the authorization code from the authorization response
  • scope: the scope requested for the access token. Scope can be 'read', 'write', or 'read write'.
  • redirectURI: the redirect URI

Example

Using the example values below, the following is the resulting access token request:

  • orgId: apiexample
  • clientId: 8ZgZxV9B8rdwVXJ8lzuh
  • clientSecret: fc7bad78c5ba4cebaac0bfb973a06dc3
  • authorizationCode: G7bM5f
  • scope: read
  • redirectURI: https://www.google.com

POST /oauth/v1/token HTTP/1.1
Host: apiexample.memberclicks.net
Authorization: Basic OFpnWnhWOUI4cmR3VlhKOGx6dWg6ZmM3YmFkNzhjNWJhNGNlYmFhYzBiZmI5NzNhMDZkYzM=
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache

grant_type=authorization_code&code=G7bM5f&scope=read&redirect_uri=https://www.google.com

Access Token Response

After a successful access token request, the access token response returns an HTTP status 200 OK with the access token included in the response body.  

The following is the format of the access token response:

HTTP/1.1 200 OK

{
  "access_token": <accessToken>,
  "token_type": <tokenType>,
  "refresh_token": <refreshToken>,
  "expires_in": <expiresIn>,
  "scope": <scope>,
  "serviceId": <serviceId>,
  "userId": <userId>,
  "jti": <jti>
}

  • accessToken: the access token for accessing the resource server
  • tokenType: the token type of this access token
  • refreshToken: the refresh token for requesting a new access token if enabled
  • expiresIn: the time in seconds that the token will expire.  This is initially set to 3600 (1 hour).
  • scope: the scope granted to this access token. Scope can be 'read', 'write', or 'read write'.
  • serviceId: the MC Professional service ID
  • userId: the user ID associated with the access token
  • jti: JSON Web Token ID

Example

The following is the access token response from the example access token request above:

HTTP/1.1 200 OK

{
  "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE0NjcyMDU5OTUsInVzZXJfbmFtZSI6IjEwMDEzNDU2MzAiLCJzY29wZSI6WyJyZWFkIl0sInNlcnZpY2VJZCI6NzM0MCwiYXV0aG9yaXRpZXMiOlsiUk9MRV9VU0VSIl0sInVzZXJJZCI6MTAwMTM0NTYzMCwianRpIjoiY2JhMTIyNGQtYmUyMi00YWJkLWEwOGItY2JmN2VjOTBmMTczIiwiY2xpZW50X2lkIjoiOFpnWnhWOUI4cmR3VlhKOGx6dWgifQ.ILtkgzP5CY0tTEyDdcHvu_rN3u1csgsN6UWJo98mfW4",
  "token_type": "bearer",
  "refresh_token": "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE0Njk3OTQzOTUsInVzZXJfbmFtZSI6IjEwMDEzNDU2MzAiLCJzY29wZSI6WyJyZWFkIl0sInNlcnZpY2VJZCI6NzM0MCwiYXV0aG9yaXRpZXMiOlsiUk9MRV9VU0VSIl0sInVzZXJJZCI6MTAwMTM0NTYzMCwianRpIjoiYWY4NDM4Y2UtZTg5NC00YWM5LWE3ZmQtZDIyMDFiN2RhYjAwIiwiY2xpZW50X2lkIjoiOFpnWnhWOUI4cmR3VlhKOGx6dWgiLCJhdGkiOiJjYmExMjI0ZC1iZTIyLTRhYmQtYTA4Yi1jYmY3ZWM5MGYxNzMifQ.6O9rdGwAOWe2Ot0LNKNF3JDUoOfChQkJ5nHAlCUjO-o",
  "expires_in": 3599,
  "scope": "read",
  "serviceId": 7340,
  "userId": 1001345630,
  "jti": "cba1224d-be22-4abd-a08b-cbf7ec90f173"
}

Implicit Grant Type

Overview

The Implicit grant type is used to obtain access tokens only.  Refresh tokens are not supported with this grant type.

This grant type requires the interaction of the resource owner (a member of the organization) and involves redirection from the MC Professional site to the 3rd party client system.  The resource owner provides their username and password on the MC Professional site if not already logged in.

Flow

With the Implicit grant type, the resource owner typically starts on the 3rd party client site.  To initiate the authorization process, the resource owner clicks a link to the MC Professional authorization server.  This link contains the client ID as one of the request parameters.  

  • If the resource owner is already logged in to the MC Professional site, they will be redirected immediately to the specified redirect URI.  
  • If the resource owner is not already logged in to the MC Professional site, they are taken to the login page to enter their username and password.  After successful login they are redirected to the specified redirect URI.

The redirect URI should point to a location controlled by the 3rd party client.  MC Professional will add the access token to the redirect URI fragment.  The 3rd party client system will parse the access token from the redirect URI fragment.

API_Implicit_Grant_Type_Flow.svg

Authorization Request

The authorization request is an HTTP GET to the /oauth/v1/authorize endpoint.  This is typically a link that a resource owner clicks in their browser.  

The following is the format of the authorization request:

https://<orgId>.memberclicks.net/oauth/v1/authorize?response_type=token&client_id=<clientId>&scope=<scope>&state=<state>&redirect_uri=<redirectURI>

  • orgId: the MC Professional organization ID
  • clientId: the client ID configured in API Management for the 3rd party client
  • scope: the scope requested for the access token. Scope can be 'read', 'write', or 'read write'.
  • state (optional but recommended): a unique value that will be returned in the authorization response.  This value can be used by the 3rd party system to maintain state and to prevent cross-site request forgery.
  • redirectURI (optional but recommended): a URL encoded redirect URI configured in API Management for the 3rd party client.  The resource owner will be redirected to this URI after successful login.  Note: The redirectURI is required if more than one redirect URI is configured for this 3rd party client.

Example

Using the example values below, the following is the resulting authorization request:

  • orgId: apiexample
  • clientId: 8ZgZxV9B8rdwVXJ8lzuh
  • scope: read
  • state: 8d152e78-3df5-11e6-ac61-9e71128cae77
  • redirectURI: https://www.google.com

https://apiexample.memberclicks.net/oauth/v1/authorize?response_type=token&client_id=8ZgZxV9B8rdwVXJ8lzuh&scope=read&state=8d152e78-3df5-11e6-ac61-9e71128cae77&redirect_uri=https%3A%2F%2Fwww.google.com

Authorization Response

After successful login, the authorization response returns an HTTP status 302 Found with a location set to the redirect URI specified in the authorization request and the access token in the URI fragment.  

The following is the format of the authorization response redirect URI:

HTTP/1.1 302 Found
Location: <redirectURI>#access_token=<accessToken>&token_type=<tokenType>&state=<state>&expires_in=<expiresIn>&serviceId=<serviceId>&userId=<userId>&jti=<jti>

  • redirectURI: the redirect URI specified in the authorization request
  • accessToken: the access token for accessing the resource server
  • tokenType: the token type of the access token
  • state: the state if included in the authorization request
  • expiresIn: the time in seconds that the token will expire.  This is initially set to 3600 (1 hour).
  • serviceId: the MC Professional service ID
  • userId: the user ID associated with the access token
  • jti: JSON Web Token ID

Example

The following is the authorization response from the example authorization request above:

HTTP/1.1 302 Found
Location: https://www.google.com/#access_token=eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE0NjcyMDcxODUsInVzZXJfbmFtZSI6IjEwMDEzNDU2MzAiLCJzY29wZSI6WyJyZWFkIl0sInNlcnZpY2VJZCI6NzM0MCwiYXV0aG9yaXRpZXMiOlsiUk9MRV9VU0VSIl0sInVzZXJJZCI6MTAwMTM0NTYzMCwianRpIjoiYzI0ZDc3ZmEtN2FmOC00YzFkLTgwMTUtYTIyNDA2MjQyNzRhIiwiY2xpZW50X2lkIjoiOFpnWnhWOUI4cmR3VlhKOGx6dWgifQ.-O4kOt9XMsNfnS_UsgCD7Ti0CJFwIj40TvLihFeIFTk&token_type=bearer&state=8d152e78-3df5-11e6-ac61-9e71128cae77&expires_in=3599&serviceId=7340&userId=1001345630&jti=c24d77fa-7af8-4c1d-8015-a2240624274a

Resource Owner Password Credentials Grant Type

Overview

The Resource Owner Password Credentials grant type is used to obtain access tokens and refresh tokens if enabled.

This grant type requires the interaction of the resource owner (a member of the organization).  The resource owner provides their username and password on the 3rd party client site.  The 3rd party client system passes the client ID, client secret, resource owner's username and password to the MC Professional authorization server.  It is the responsibility of the 3rd party system to protect the resource owner's username and password.

Flow

With the Resource Owner Password Credentials grant type, the resource owner is on the 3rd party client site.  To initiate the authorization process, the 3rd party client site will prompt the resource owner for their MC Professional username and password.  Then the 3rd party client system will make a request to the MC Professional authorization server using the client ID, client secret, resource owner's username and password to obtain an access token and refresh token if enabled.  The 3rd party client system is responsible for protecting the resource owner's login credentials and must not store the password.

API_Resource_Owner_Password_Credentials_Grant_Type_Flow.svg

Access Token Request

The access token request is an HTTP POST to the /oauth/v1/token endpoint.  The client ID and client secret are encoded in the Authorization header using HTTP Basic Access Authentication and the resource owner's username and password are included in the POST body. 

The following is the format of the access token request:

POST /oauth/v1/token HTTP/1.1
Host: <orgId>.memberclicks.net
Authorization: Basic <clientCredentials>
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache

grant_type=password&scope=<scope>&refresh_token=<refreshToken>

  • orgId: the MC Professional organization ID
  • clientCredentials: Base64 encoded <clientId>:<clientSecret>
  • clientId: the client ID configured in API Management for the 3rd party client
  • clientSecret: the client secret configured in API Management for the 3rd party client
  • scope: the scope requested for the access token. Scope can be 'read', 'write', or 'read write'.
  • username: the resource owner's username
  • password: the resource owner's password

Example

Using the example values below, the following is the resulting access token request:

  • orgId: apiexample
  • clientId: 8ZgZxV9B8rdwVXJ8lzuh
  • clientSecret: fc7bad78c5ba4cebaac0bfb973a06dc3
  • scope: read
  • username: admin
  • password: mypassword

POST /oauth/v1/token HTTP/1.1
Host: apiexample.memberclicks.net
Authorization: Basic OFpnWnhWOUI4cmR3VlhKOGx6dWg6ZmM3YmFkNzhjNWJhNGNlYmFhYzBiZmI5NzNhMDZkYzM=
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache

grant_type=password&scope=read&username=admin&password=mypassword

Access Token Response

After a successful access token request, the access token response returns an HTTP status 200 OK with the access token included in the response body.  

The following is the format of the access token response:

HTTP/1.1 200 OK

{
  "access_token": <accessToken>,
  "token_type": <tokenType>,
  "refresh_token": <refreshToken>,
  "expires_in": <expiresIn>,
  "scope": <scope>,
  "serviceId": <serviceId>,
  "userId": <userId>,
  "jti": <jti>
}

  • accessToken: the access token for accessing the resource server
  • tokenType: the token type of this access token
  • refreshToken: the refresh token for requesting a new access token if enabled
  • expiresIn: the time in seconds that the token will expire.  This is initially set to 3600 (1 hour).
  • scope: the scope granted to this access token. Scope can be 'read', 'write', or 'read write'.
  • serviceId: the MC Professional service ID
  • userId: the user ID associated with the access token
  • jti: JSON Web Token ID

Example

The following is the access token response from the example access token request above:

HTTP/1.1 200 OK

{
  "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE0NjcyMDUzMzMsInVzZXJfbmFtZSI6IjEwMDEzNDU2MzAiLCJzY29wZSI6WyJyZWFkIl0sInNlcnZpY2VJZCI6NzM0MCwiYXV0aG9yaXRpZXMiOlsiUk9MRV9VU0VSIl0sInVzZXJJZCI6MTAwMTM0NTYzMCwianRpIjoiNzUxMDBkZWYtNzU1OS00ZmEwLWFmNDUtYjY5YzNjNDY5NzJlIiwiY2xpZW50X2lkIjoiOFpnWnhWOUI4cmR3VlhKOGx6dWgifQ.TOLLpnlJZxUdTZsdl1g6-45AYAB-5em8WfKqV46e9Fg",
  "token_type": "bearer",
  "refresh_token": "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE0Njk3OTM3MzMsInVzZXJfbmFtZSI6IjEwMDEzNDU2MzAiLCJzY29wZSI6WyJyZWFkIl0sInNlcnZpY2VJZCI6NzM0MCwiYXV0aG9yaXRpZXMiOlsiUk9MRV9VU0VSIl0sInVzZXJJZCI6MTAwMTM0NTYzMCwianRpIjoiMjI1YmJmZjQtZmZjOC00YjFlLTk4YTktMTliY2Q0Mjc5MGExIiwiY2xpZW50X2lkIjoiOFpnWnhWOUI4cmR3VlhKOGx6dWgiLCJhdGkiOiI3NTEwMGRlZi03NTU5LTRmYTAtYWY0NS1iNjljM2M0Njk3MmUifQ.u9CiqYlaYt2MGzpUO68LIsBRBwuK6Tg4MKUSM09AavI",
  "expires_in": 3599,
  "scope": "read",
  "serviceId": 7340,
  "userId": 1001345630,
  "jti": "75100def-7559-4fa0-af45-b69c3c46972e"
}

Client Credentials Grant Type

Overview

The Client Credentials grant type is used to obtain access tokens only.  Refresh tokens are not supported with this grant type.

This grant type does not require the interaction of the resource owner (a member of the organization).  The 3rd party client system passes the client ID and client secret to the MC Professional authorization server.

Flow

With the Client Credentials grant type, the 3rd party client system initiates the authorization process by making a request to the MC Professional authorization server using the client ID and client secret.  This grant type is for highly trusted clients and is useful for 3rd pary client systems using the API to run batch or background operations without the interaction of the resource owner.

API_Client_Credentials_Grant_Type_Flow.svg

Access Token Request

The access token request is an HTTP POST to the /oauth/v1/token endpoint.  The client ID and client secret are encoded in the Authorization header using HTTP Basic Access Authentication.  

The following is the format of the access token request:

POST /oauth/v1/token HTTP/1.1
Host: <orgId>.memberclicks.net
Authorization: Basic <clientCredentials>
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache

grant_type=client_credentials&scope=<scope>

  • orgId: the MC Professional organization ID
  • clientCredentials: Base64 encoded <clientId>:<clientSecret>
  • clientId: the client ID configured in API Management for the 3rd party client
  • clientSecret: the client secret configured in API Management for the 3rd party client
  • scope: the scope requested for the access token. Scope can be 'read', 'write', or 'read write'.

Example

Using the example values below, the following is the resulting access token request:

  • orgId: apiexample
  • clientId: 8ZgZxV9B8rdwVXJ8lzuh
  • clientSecret: fc7bad78c5ba4cebaac0bfb973a06dc3
  • scope: read

POST /oauth/v1/token HTTP/1.1
Host: apiexample.memberclicks.net
Authorization: Basic OFpnWnhWOUI4cmR3VlhKOGx6dWg6ZmM3YmFkNzhjNWJhNGNlYmFhYzBiZmI5NzNhMDZkYzM=
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache

grant_type=client_credentials&scope=read

Access Token Response

After a successful access token request, the access token response returns an HTTP status 200 OK with the access token included in the response body.  

The following is the format of the access token response:

HTTP/1.1 200 OK

{
  "access_token": <accessToken>,
  "token_type": <tokenType>,
  "expires_in": <expiresIn>,
  "scope": <scope>,
  "serviceId": <serviceId>,
  "userId": <userId>,
  "jti": <jti>
}

  • accessToken: the access token for accessing the resource server
  • tokenType: the token type of this access token
  • expiresIn: the time in seconds that the token will expire.  This is initially set to 3600 (1 hour).
  • scope: the scope granted to this access token. Scope can be 'read', 'write', or 'read write'.
  • serviceId: the MC Professional service ID
  • userId: the user ID associated with the access token
  • jti: JSON Web Token ID

Example

The following is the access token response from the example access token request above:

HTTP/1.1 200 OK

{
  "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE0NjcyMDM4NzksInNjb3BlIjpbInJlYWQiXSwic2VydmljZUlkIjo3MzQwLCJhdXRob3JpdGllcyI6WyJST0xFX1VTRVIiXSwidXNlcklkIjoxMDAxMzQ1NjM0LCJqdGkiOiJjZWY2NGVmNC0zN2JjLTQyMTUtYjhjYi00Y2ViNzFlYWNmZjUiLCJjbGllbnRfaWQiOiI4WmdaeFY5QjhyZHdWWEo4bHp1aCJ9.tMldY4w43pz4LzFqFIagClwu9ZparqOI_OhiHlW5LIQ",
  "token_type": "bearer",
  "expires_in": 3599,
  "scope": "read",
  "serviceId": 7340,
  "userId": 1001345634,
  "jti": "cef64ef4-37bc-4215-b8cb-4ceb71eacff5"
}

Refresh Token Grant Type

Overview

The Refresh Token grant type is used to obtain access tokens and refresh tokens.

This grant type does not require the interaction of the resource owner (a member of the organization).  The 3rd party client system passes the client ID, client secret and refresh token to the MC Professional authorization server. 

Refresh tokens can only be obtained from the access token response of Authorization Code and Resource Owner Password Credentials grant types.  Refresh tokens are valid for 30 days.

Flow

With the Refresh Token grant type, the 3rd party client system initiates the authorization process by making a request to the MC Professional authorization server using the client ID, client secret and refresh token.

API_Refresh_Token_Grant_Type_Flow.svg

Access Token Request

The access token request is an HTTP POST to the /oauth/v1/token endpoint.  The client ID and client secret are encoded in the Authorization header using HTTP Basic Access Authentication and the refresh token is included in the POST body.  

The following is the format of the access token request:

POST /oauth/v1/token HTTP/1.1
Host: <orgId>.memberclicks.net
Authorization: Basic <clientCredentials>
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache

grant_type=refresh_token&scope=<scope>&refresh_token=<refreshToken>

  • orgId: the MC Professional organization ID
  • clientCredentials: Base64 encoded <clientId>:<clientSecret>
  • clientId: the client ID configured in API Management for the 3rd party client
  • clientSecret: the client secret configured in API Management for the 3rd party client
  • scope: the scope requested for the access token. Scope can be 'read', 'write', or 'read write'.
  • refreshToken: the refresh token

Example

Using the example values below, the following is the resulting access token request:

  • orgId: apiexample
  • clientId: 8ZgZxV9B8rdwVXJ8lzuh
  • clientSecret: fc7bad78c5ba4cebaac0bfb973a06dc3
  • scope: read
  • refreshToken: eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE0Njk3OTA5NTEsInVzZXJfbmFtZSI6IjEwMDEzNDU2MzAiLCJzY29wZSI6WyJyZWFkIl0sInNlcnZpY2VJZCI6NzM0MCwiYXV0aG9yaXRpZXMiOlsiUk9MRV9VU0VSIl0sInVzZXJJZCI6MTAwMTM0NTYzMCwianRpIjoiMmRlNjBiZjQtZDgxNy00NzhmLTg3YmMtMmZmY2Y0NWJiMTk3IiwiY2xpZW50X2lkIjoiOFpnWnhWOUI4cmR3VlhKOGx6dWgiLCJhdGkiOiI3MWI3MGMxZS0zMjg1LTQwY2MtYWI1ZC1mOWIxNTZmMTI3MjkifQ.69jhxNZ8meGNKTAc1WZWud54o6wE0ia3rwctASZWrpQ

POST /oauth/v1/token HTTP/1.1
Host: apiexample.memberclicks.net
Authorization: Basic OFpnWnhWOUI4cmR3VlhKOGx6dWg6ZmM3YmFkNzhjNWJhNGNlYmFhYzBiZmI5NzNhMDZkYzM=
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache

grant_type=refresh_token&scope=read&refresh_token=eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE0Njk3OTA5NTEsInVzZXJfbmFtZSI6IjEwMDEzNDU2MzAiLCJzY29wZSI6WyJyZWFkIl0sInNlcnZpY2VJZCI6NzM0MCwiYXV0aG9yaXRpZXMiOlsiUk9MRV9VU0VSIl0sInVzZXJJZCI6MTAwMTM0NTYzMCwianRpIjoiMmRlNjBiZjQtZDgxNy00NzhmLTg3YmMtMmZmY2Y0NWJiMTk3IiwiY2xpZW50X2lkIjoiOFpnWnhWOUI4cmR3VlhKOGx6dWgiLCJhdGkiOiI3MWI3MGMxZS0zMjg1LTQwY2MtYWI1ZC1mOWIxNTZmMTI3MjkifQ.69jhxNZ8meGNKTAc1WZWud54o6wE0ia3rwctASZWrpQ

Access Token Response

After a successful access token request, the access token response returns an HTTP status 200 OK with the access token included in the response body.  

The following is the format of the access token response:

HTTP/1.1 200 OK

{
  "access_token": <accessToken>,
  "token_type": <tokenType>,
  "refresh_token": <refreshToken>,
  "expires_in": <expiresIn>,
  "scope": <scope>,
  "serviceId": <serviceId>,
  "userId": <userId>,
  "jti": <jti>
}

  • accessToken: the access token for accessing the resource server
  • tokenType: the token type of this access token
  • refreshToken: the refresh token for requesting a new access token
  • expiresIn: the time in seconds that the token will expire.  This is initially set to 3600 (1 hour).
  • scope: the scope granted to this access token. Scope can be 'read', 'write', or 'read write'.
  • serviceId: the MC Professional service ID
  • userId: the user ID associated with the access token
  • jti: JSON Web Token ID

Example

The following is the access token response from the example access token request above:

HTTP/1.1 200 OK

{
  "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE0NjcyMDI1NjksInVzZXJfbmFtZSI6IjEwMDEzNDU2MzAiLCJzY29wZSI6WyJyZWFkIl0sInNlcnZpY2VJZCI6NzM0MCwiYXV0aG9yaXRpZXMiOlsiUk9MRV9VU0VSIl0sInVzZXJJZCI6MTAwMTM0NTYzMCwianRpIjoiNTQzYWQ4ZmItODEwZC00ZWM4LWE3ZDQtZjhiYWY2OGViOGZkIiwiY2xpZW50X2lkIjoiOFpnWnhWOUI4cmR3VlhKOGx6dWgifQ.lkd42FydqVZ6308pNWKelPZTHrTFX1xf9DnSbR78uGs",
  "token_type": "bearer",
  "refresh_token": "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE0Njk3OTA5NTEsInVzZXJfbmFtZSI6IjEwMDEzNDU2MzAiLCJzY29wZSI6WyJyZWFkIl0sInNlcnZpY2VJZCI6NzM0MCwiYXV0aG9yaXRpZXMiOlsiUk9MRV9VU0VSIl0sInVzZXJJZCI6MTAwMTM0NTYzMCwianRpIjoiMmRlNjBiZjQtZDgxNy00NzhmLTg3YmMtMmZmY2Y0NWJiMTk3IiwiY2xpZW50X2lkIjoiOFpnWnhWOUI4cmR3VlhKOGx6dWgiLCJhdGkiOiI1NDNhZDhmYi04MTBkLTRlYzgtYTdkNC1mOGJhZjY4ZWI4ZmQifQ.efe6MsfCrdzRx6PeC2OWRui3q1Wv1EY99n0ECaw92uU",
  "expires_in": 3599,
  "scope": "read",
  "serviceId": 7340,
  "userId": 1001345630,
  "jti": "543ad8fb-810d-4ec8-a7d4-f8baf68eb8fd"
}

 

Related articles