Since posting this article, Postman has updated its layout a little bit. Because of this, some screenshots are not correct anymore. However, the steps are still correct and valid. Once I have the time, I will update the screenshots to show the latest Postman version again.
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.
Before you can start with the API's, you should install Postman. This 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.
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:
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
- Go to setup – AppCloud Developer
- 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
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:
Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3
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).
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:
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.
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.
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.
|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|