Authenticate using OAuth 2.0

In general, OAuth authentication follows a six step pattern:

1. An application requests authorization on a user's behalf.
2. The application obtains a Grant Token.
3. The client requests an access token by using the Grant Token.
4. The authorization server validates the Grant Token and issues an Access Token and a Refresh Token.
5. The client requests the protected resource, authenticating using the Access Token.
6. The resource server verifies the Access Token and serves the request.

Learn more about the OAuth 2.0 Specifications.

In this topic:

• Authenticate using OAuth 2.0
• Eloqua OAuth 2.0 endpoints:
• To authenticate using OAuth 2.0
• To authenticate using an authorization code grant:
• To authenticate using an implicit grant:
• To authenticate using a resource owner password credentials grant
• Troubleshooting error messages

Eloqua OAuth 2.0 endpoints:

Authorization endpoint: https://login.eloqua.com/auth/oauth2/authorize

Token endpoint: https://login.eloqua.com/auth/oauth2/token

Note: The following examples assume that all requests are successful. For a detailed description of possible request responses, including a variety of failure types, see: the OAuth Reference.

To authenticate using an authorization code grant:

1. Request initial authorization through the login.eloqua.com/auth/oauth2/authorize endpoint. A call to this endpoint will trigger a prompt for users to enter their credentials.

   /auth/oauth2/authorize has five possible URL parameters:

   Parameter	Value	Required?
   response_type	Must be "code"	Yes
   client_id	Your app's Client Id provided when registering your app (see above)	Yes
   redirect_uri	Your app's registered redirection endpoint, should be the same URL you entered as the Callback Url when registering your app (see above)	Yes
   scope	Must be “full” or not supplied	No
   state	An optional value that has meaning for your App	No

   The call to the authorize endpoint might resemble:

   https://login.eloqua.com/auth/oauth2/authorize?response_type=code
   &client_id=a1b2c3d4&redirect_uri=https://client.example.com/cb
   &scope=full&state=xyz
   

   Once users enter their credentials and accept your app's request to access Eloqua on their behalf, they are redirected to the redirect_uri with a Grant Token (which is in this case an Authorization Code) attached in the code URL parameter, as in the following example:

   HTTP/1.1 302 Found
   Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA&state=xyz

2. Use the Grant Token to obtain an Access Token and Refresh Token using a POST request to the login.eloqua.com/auth/oauth2/token endpoint.

   The POST request should include a JSON body with the following parameters:

   Parameter	Value	Required?
   grant_type	The name of the Grant Token's type. In this case: authorization_code	Yes
   code	The Grant Token	Yes
   redirect_uri	Your app's registered redirection endpoint	Yes

   The following example call requests an Access Token and a Refresh Token token using the Grant Token obtained previously:

   POST https://login.eloqua.com/auth/oauth2/token
   Authorization: Basic Q09NUEFOWVhcdXNlcjE6cGFzc3dvcmQxMjM=
   {
      "grant_type":"authorization_code",
      "code":"SplxlOBeZQQYbYS6WxSbIA",
      "redirect_uri":"https://client.example.com/cb"
   }
   

   Note: This request must authenticate using HTTP basic. Use your app’s Client Id as the username and its Client Secret as the password. The format is client_id:client_secret. Encode the string with base-64 encoding, and you can pass it as an authentication header. The system does not support passing Client Id and Client Secret parameters in the JSON body, and, unlike basic authentication elsewhere, you should not include your site name. Learn more about basic authentication with Eloqua.

   The authorization server validates the authorization code and if valid responds with a JSON body containing the Access Token, Refresh Token, access token expiration time, and token type, as in the following example:

   HTTP/1.1 200 OK
   Content-Type: application/json
   {
      "access_token":"2YotnFZFEjr1zCsicMWpAA",
      "token_type":"bearer",
      "expires_in":3600,
      "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA"
   }

3. Store and use the access and refresh tokens.

   When your app needs a protected resource, it authenticates during the request using the Access Token. The following call to Eloqua's application API uses the access token to authenticate:

   GET /resource/1 HTTP/1.1
   Host: api.eloqua.com
   Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
   

   api.eloqua.com verifies the Access Token, and supplies the requested resource if the access token is valid.

   Note:

   • Authorization Codes expire in 60 seconds (intended for immediate use)
   • Access Tokens expire in 8 hours
   • Refresh Tokens expire in 1 year
   • Refresh Tokens will expire immediately after being used to obtain new tokens, or after 1 year if they are not used to obtain new tokens
4. If the access token has expired, you should send your Refresh Token to login.eloqua.com/auth/oauth2/token to obtain new tokens as in the following example:

   POST https://login.eloqua.com/auth/oauth2/token
   Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3
   {
      "grant_type":"refresh_token",
      "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
      "scope":"full",
      "redirect_uri":"https://client.example.com/cb"
   }
   

   If the request is successful, the response is a JSON body containing a new access token, token type, access token expiration time, and new refresh token:

   HTTP/1.1 200 OK 
   Content-Type: application/json
   {
      "access_token":"2YotnFZFEjr1zCsicMWpAA",
      "token_type":"bearer",
      "expires_in":3600,
      "refresh_token":"MToxLUIyZHRNTUZsazIwNmZFTy1"
   }
   

   Store the new refresh token as the old refresh token is no longer valid. Then proceed to make your call using the new access token.

To authenticate using an implicit grant:

An implicit grant is a browser-based authentication best used for in-browser applications and instead of issuing an authorization code that is exchanged for an access token, Eloqua issues an access token directly.

1. Request an access token through a GET request to the login.eloqua.com/auth/oauth2/authorize endpoint using the following URL parameters:

   Parameter	Value	Required?
   response_type	Must be "token"	Yes
   client_id	Your app's Client Id provided when registering your app (see above)	Yes
   redirect_uri	Your app's registered redirection endpoint, should be the same URL you entered as the Callback Url when registering your app (see above)	Yes
   scope	Must be “full” or not supplied	No
   state	An optional value that has meaning for your App	No

   The call to the authorize endpoint might resemble:

   https://login.eloqua.com/auth/oauth2/authorize?response_type=token
   &client_id=s6BhdRkqt3&redirect_uri=https://client.example.com/app
   &scope=full&state=xyz
   

   Once users enter their credentials and accept your app's request to access Eloqua on their behalf, they are redirected to the redirect_uri with an authorization code attached in the access_token URL parameter, as in the following example:

   HTTP/1.1 302 Found
   Location: https://client.example.com/cb#access_token=2YotnFZFEjr1zCsicMWpAA
   &token_type=bearer&expires_in=28800&state=xyz
   

2. Use the access token to request resources on the user's behalf.

To authenticate using a resource owner password credentials grant

With the resource owner password credential grant, the App provides the resource owner's username and password to the authorization server in order to obtain an access token. This grant type is ideal when an app already has the necessary Eloqua user names and passwords stored, and wants to use access tokens for added security.

1. Obtain an Access Token and a Refresh Token by making a POST request to the login.eloqua.com/auth/oauth2/token endpoint using a JSON body containing the following parameters:

   Parameter	Value	Required?
   grant_type	Must be "password"	Yes
   scope	Must be "full" or not supplied	No
   username	The user's site name and username in the form sitename + '/' + username	Yes
   password	The user's password	Yes

   Note: This request must authenticate using HTTP basic. Use your app’s Client Id as the username and its Client Secret as the password. The format is client_id:client_secret. Encode the string with base-64 encoding, and you can pass it as an authentication header. The system does not support passing Client Id and Client Secret parameters in the JSON body, and, unlike basic authentication elsewhere, you should not include your site name. Learn more about basic authentication with Eloqua.

   The call to the token endpoint might resemble:

   POST https://login.eloqua.com/auth/oauth2/token
   Authorization: Basic Q09NUEFOWVhcdXNlcjE6cGFzc3dvcmQxMjM=
   {
      "grant_type":"password",
      "scope":"full",
      "username":"testsite\\testuser",
      "password":"user123"
   }
   

2. If the request is successful, the response is a JSON body containing an Access Token, a Refresh Token, the access token expiration time, and token type:

   HTTP/1.1 200 OK
   Content-Type: application/json
   {
      "access_token":"2YotnFZFEjr1zCsicMWpAA",
      "token_type":"bearer",
      "expires_in":3600,
      "refresh_token":"tGzv3JOkF0XG5Qx2TlKW"
   }
   

3. You can then use the Access Token and store the Refresh Token, using the Refresh Token as needed to renew the credentials. Follow steps 3 and 4 of "To authenticate using an authorization code grant" above for more information.