Home / APIs / Fuel API Family - Auth

Fuel API Family - Auth

8232 points
Michael Clark's picture

 

Overview

The Auth service provides OAuth tokens you can use to authenticate with Fuel APIs.

Resource URL

https://auth.exacttargetapis.com/v1/requestToken

Sandbox Environment Resource URL

https://auth-test.exacttargetapis.com/v1/requestToken

JSON Parameters:

  • clientId (Required) - First part of the App Key pair generated when creating an application in App Center
  • clientSecret (Required) - Second part of the App Key pair generated when creating an application in App Center
  • accessType - Used to return a RefreshToken for later use when set to offline
  • refreshToken - Used to pass the RefreshToken obtained through SSO for Hub Applications or using the accessType option
  • scope - Used to specify a user account for the returned access token 

Do not share Application Signature with those outside your organization. Additionally, take special care to ensure your API Keys (clientId, clientSecret, appSignature) and refreshToken are ALWAYS kept in server-side code (not ever passed to the browser)!

URL Parameters:

  • legacy - If set to 1, it will return a token (legacyToken) which can be used to access the Email SOAP API. This value is referred to as the internalOauthToken when using the JWT payload in the single sign-on solution.

Usage

To obtain an OAuth token, perform a HTTP POST to the resource URL above, specifying your API key Client ID and Client Secret in the payload of the HTTP POST (see the Getting Started Guide for more information about API keys). For example:

POST https://auth.exacttargetapis.com/v1/requestToken
Content-Type: application/json
{
  "clientId": "gyjzvytv7ukqtfn3x2qdyfsn",
  "clientSecret": "tv7ukqtfn3x2"
}

The HTTP POST with valid values for clientID and clientSecret returns two values:

  1. accessToken - an OAuth token passed to subsequent API requests
  2. expiresIn - the expiration period of the OAuth token in seconds

For example:

{
  "accessToken": "gd2324hruukedkremtwqhae9",
  "expiresIn": 3600
}

Using an OAuth Token

Once you obtain an OAuth token, pass that token to subsequent API requests Within the Header

An alternate method for providing the OAuth token for a request is to pass it in the Authorization header field with the Bearer HTTP authorization scheme:

GET https://www.exacttargetapis.com/platform/v1/tokenContext/
Authorization: Bearer gd2324hruukedkremtwqhae9

Expiration

The expiration period for an access token is 3,600 seconds, or one hour. After the expiration period, you will need to request a new access token. Any attempt to use an expired token generates the following response:

Content-Type: text/xml
HTTP/1.1 401 Unauthorized

<h1>Not Authorized</h1>

Refresh Tokens

Use a refresh token when working in a Hub Application using SSO because a user can be logged into a Hub Application long enough for the original access token to expire. Using the Refresh Token when requesting a new access token ensures that the token remains in the context of the logged-in user. Any requests made using that access token will correctly correlate to that original user account.

When using a refresh token to obtain a new access token, set the accessType property on the request to offline in ensure that you receive another refresh token. A session open for an extended period of time may require several tokens. After receiving new tokens using a refresh token, the original tokens will remain valid until their original expiration time.

Refresh Token Implementation Restrictions

Here are some restrictions you should be aware of in your implementing code:

  • Only use the refreshToken parameter in the payload if you need a new access_token
  • The refreshToken provided MUST NOT have been used previously, or we will receive a 401 Unauthorized

Here's an example payload structure you should follow:

{"clientId": "", "clientSecret": "", "refreshToken": "", "accessType": "offline"}

When you use this structure to receive a new accessToken, you'll also receive a new refreshToken. This newly provided refreshToken must be used in the subsequent call to get a new accessToken, since the previous refreshToken is now invalid (since we've used it once).

API Console

Product Group: