Authenticate using OAuth 2.0
OAuth 2.0 enables the safe retrieval of secure resources while protecting user credentials. Some apps may need to authenticate during the configuration phase and others may need OAuth only when a user invokes a service.
In general, OAuth authentication follows a six step pattern:
- An application requests authorization on a user's behalf.
- The application obtains a Grant Token.
- The client requests an access token by using the Grant Token.
- The authorization server validates the Grant Token and issues an Access Token and a Refresh Token.
- The client requests the protected resource, authenticating using the Access Token.
- The resource server verifies the Access Token and serves the request.
Learn more about the OAuth 2.0 Specifications.
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: OAuth Reference.To authenticate using OAuth 2.0
Eloqua supports three possible flows that an application can use to obtain access on behalf of a resource owner: Authorization Code grant, Implicit grant, Resource Owner Password Credentials grant. In general, you should use the Authorization Code grant for Apps that extend Eloqua's functionality.
Note:
Before you begin, you'll need a unique Client Id and Client Secret for your app. In your Eloqua instance navigate to Settings > AppCloud Developer then select Create New App. Learn more about AppCloud app creation. Fill out the required information and enter your app's URL into the Callback Url field under the OAuth heading then click Save. You should then be presented with valid Client Id and Client Secret values.To authenticate using an authorization code grant:
-
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 suppliedNo 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
-
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 isclient_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:
{ "access_token":"2YotnFZFEjr1zCsicMWpAA", "token_type":"bearer", "expires_in":3600, "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA" }
-
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 Rest 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
-
If the access token has expired, you should send your stored 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:
{ "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.
Note:
An authorization code grant is recommended in the vast majority of cases as it has fewer potentially negative security implications.-
Request an access token through a
GET
request to thelogin.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 theaccess_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=86400&state=xyz
-
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.
-
Obtain an Access Token and a Refresh Token by making a
POST
request to thelogin.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 suppliedNo 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 isclient_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" }
-
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:
{ "access_token":"2YotnFZFEjr1zCsicMWpAA", "token_type":"bearer", "expires_in":3600, "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA" }
-
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.