Authenticate using OAuth 2.0 (2024)

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
• 401 Unauthorized
• Too Many Requests

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:

   See Also

   What is OAuth Authentication? Explanation and ExamplesWhy Is There No Auth In OAuth?Why OAuth Is Better Than Basic Authentication

   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 theredirect_uri with a Grant Token (which is in this case an Authorization Code) attached in the code URLparameter, 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 thefollowing 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/tokenAuthorization: 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 theusername 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 authenticationheader. The system does not support passing Client Id and Client Secret parameters inthe JSON body, and, unlike basic authentication elsewhere, you should notinclude 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 OKContent-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 duringthe request using the Access Token. The following call to Eloqua's application API uses the access tokento authenticate:

   GET /resource/1 HTTP/1.1Host: api.eloqua.comAuthorization: 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 tokenhas expired, you should send your Refresh Token tologin.eloqua.com/auth/oauth2/token to obtain new tokens as in the following example:

   POST https://login.eloqua.com/auth/oauth2/tokenAuthorization: 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 containinga 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 newaccess token.

To authenticate using an implicit grant:

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

Warning: An authorization code grant is recommended in the vast majority of cases as it has fewer potentiallynegative security implications.

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

   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 theredirect_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 formsitename + '/' + username	Yes
   password	The user's password	Yes

   Note: This request must authenticate using HTTP basic. Use your app’s Client Id as theusername 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 authenticationheader. The system does not support passing Client Id and Client Secret parameters inthe JSON body, and, unlike basic authentication elsewhere, you should notinclude 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/tokenAuthorization: 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 OKContent-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.