Originally posted on Eloqua Topliners

 

This post is written to help everyone who is interested in starting with the REST & Bulk API’s. The basic authentication is the easiest to start with, and OAuth2.0 access token and refresh token take some more time to set up. Oracle states throughout their documentation that basic Authentication should only be used for testing purposes and never for actual integrations (because of security reasons). In case you are building a custom integration with a back-end system, it is best to stick to the OAuth2.0 method. 

Installing Postman

Before you can start with the API’s, you should install PostmanThis app makes API development faster, easier, and better. The free app is used by more than 3.5 million developers and 30,000 companies worldwide. Postman is designed with the developer in mind, and packed with features and options.

Basic Authentication

For the basic authentication you do not need to to much work to get it working, the main thing you need to do is encode your login details.

Create Authorization code by going to for example to www.base64decode.org, encode your sitename, username and password in the following setup:

siteName + ‘\’ + username + ‘:’ + password

For example, with the site name of “TESTCOMPANY”, username of “testuser”, and password of “testpassword”, the value would be the base-64-encoded string:

TESTCOMPANY\testuser:testpassword

Within Postman you put the following information in the Header of your call:

Authorization: Basic VEVTVENPTVBBTllcdGVzdHVzZXI6dGVzdHBhc3N3b3Jk

The URL you use to connect to is dynamic, you will have have to determine to which server you have to connect. To read more about it, please go to this support document: REST API for Oracle Eloqua Marketing Cloud Service 

OAuth2.0 – Request Token

With the following steps, you are going authenticate using OAuth2.0. This is based upon the information Oracle provides within the Eloqua Developer Help Center. By doing these steps you are authenticating using the authorization code grant, however, you only have to request to token, Postman will take care of the Authorization Code and give your straight away (ok, not really straight away, since you first have to give permission) the Access and Refresh Token back.

Step 1 – Build app

  1. Go to setup – AppCloud Developer
  2. Click on “Create App”and fill in all required information. For Postman, the OAuth Callback URL is https://www.getpostman.com/oauth2/callback

Once saved open the app so that you see the following screen:

Step 2 – Set up Postman OAuth2.0

Set the authorization type to OAuth2.0 and click on “Get New Access Token”

Fill in the required fields and click on request token

  • Token name can be self chosen
  • Auth URL = https://login.eloqua.com/auth/oauth2/authorize
  • Access Token URL = https://login.eloqua.com/auth/oauth2/token
  • Client ID = available on the screen within the AppCloud Developer tab in Eloqua (which you opened after saving the App settings)
  • Client Secret = available on the screen within the AppCloud Developer tab in Eloqua (which you opened after saving the App settings)
  • Scope can be left blank
  • Grant Type = Authorization Code
  • Request Access Token locally = checked

The next step is to log in into Eloqua and approve the request for permission on the app that you have just created. Click on Log in, and enter your user details (make sure that this user has API rights within Eloqua). When this is successful you will see the Postman screen again, with a token created.

You are now able to use this token and request information from Eloqua. Make sure you are using the Token within the Header, in the screen where you can see the token you set it to be added to the header and you click on Use Token. There is a (1) placed behind the Headers tab, meaning it is successfully added.

If you then do the following GET on https://secure.[POD].eloqua.com/api/REST/1.0/system/user/[ID], you will get information back from Eloqua.

OAuth2.0 – Refresh Token

The Call

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://www.getpostman.com/oauth2/callback

}

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 (source here).

The response

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″

}

The access token you receive you will be able to use again until it is expired, the refresh token you get back you should save somewhere to refresh the next time.

Extra information

Expiration of tokens

You do not necessarily have to request a new access token every time you want to call something. Oracle has shared information on the expiration of these tokes within their Help center:

  • 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

Meaning that you can use the token you have initially requested for up to 8 hours before you have to request a new token.

Bulk API

Now that you have the API up and running you can start with understanding how the different API’s work, or you continue to the next level: Adding contacts through the Bulk API. A very clear post about this can be found here.

Useful URLs

Basic Authentication on Eloqua Developer support
Oauth2.0 Authentication on Eloqua Developer support
Postman – API development tool
Encode your login details using Base64encode.org
Determining your Base URL