Skill Level: Any
Use this tutorial to authenticate your API requests before retrieving or modifying their data. IBM supports two types of authentication, but are encouraging customers to use the newly released OAuth 2.0 system whenever appropriate because of its inherently increased security and implementation flexibility.
OAuth 2.0 authentication allows a user to POST an HTTPS request to the Acoustic Campaign server that embeds an Access Token in the response. The request includes your unique Client Id, Client Secret, and Refresh Token. All of these items are automatically provisioned to you through the Org Admin section of the Watson Campaign Automation User Interface. The response, as stated, provides you with an Access Token that has a set lifetime of 4 hours. From this point forward, all requests against the Watson Campaign Automation API can be authenticated by adding the Access Token to the header of the HTTPS request. When the Access Token expires (or is about to expire), another one can be requested which allows you to have longer term access when needed. You do not have to get the new Access Token nearly as often as you do with the JSESSIONID.
Getting Started with OAuth in the Watson Campaign Automation
Create applications that use OAuth as their authentication mechanism and represent your integrations with the Acoustic Campaign.
- Navigate to Settings > Organizaton Settings.
- Click to expand Application Account Access.
- Select Add Application.The next page will prompt you for the Name of the Application you are creating access for and a brief description.
- Enter a name and description that identifies which application is connecting to your data in the Watson Campaign Automation.
- After you click Add, you will be able to see your Client Id and Client Secret. You want to securely embed these tokens within your application.
Getting Refresh Tokens
Once you set up your application and get your Client Id and Client Secret tokens, you are ready to associate a user to that application. Users are connected to the application so that the existing built-in security model as is defined can be applied for that user for the application that is authenticating with OAuth. User name or password does not need to be, nor should it be, stored in the external application. It is only used at this stage in the process to deliver the Refresh token to the Notification Address of the user. Make sure that you create a new Org Admin user that can be used for your integration and set the notification email address to your own so that you can receive the Refresh Token email when you grant that integration user access to your new application.
- Go to Settings > Organization Settings.
- Expand Application Account Access.
- Click Add Account Access.
- Choose an Application and user Account from the dropdown and click Add.The notification email address that is specified for the user that you granted access to your new application integration receives an email with the refresh token within it.
Getting Access Tokens
You are sending an HTTP POST to the Acoustic Campaign Server, substituting the following parameters as is appropriate for your Org within the Watson Campaign Automation:
Description: Generate Access Token.
URL Endpoint: https://api[x].ibmmarketingcloud.com/oauth/token
Header: Content-Type: application/x-www-form-urlencoded
client_id=ibm generated client ID
client_secret=ibm generated client secret.
refresh_token=ibm generated refresh token.
Note: Replace [x] with your Pod number.
Once the Access Token is acquired, you can use this cryptic string value to gain access to any of the XML APIs described in this document. To call any of the APIs within this document by using the OAuth security model, you send an HTTP POST to the Watson Campaign Automation Server, substituting the following parameters as is appropriate for your Org within Watson Campaign Automation:
Description: Invoke XML API
URL Endpoint: https://api[x].ibmmarketingcloud.com/XMLAPI
Header: Authorization: Bearer access token
Note: Replace [x] with your Pod number.