Skill Level: Any


The following section defines the ways that developers can authenticate their API requests before retrieving or modifying their data. We support two types of authentication, but are encouraging our customers to use our OAuth 2.0 system whenever appropriate because of its inherently increased security and implementation flexibility.

What is OAuth?

OAuth is an open standard for authenticating APIs. 

Critical OAuth concepts

  • The client (the API caller) has identity.
  • The client accesses the server resources () on behalf of the resource owner (the user).
  • OAuth is based on tokens that represent the relationship between the client and the resource owner.
  • These tokens can be generated in such a way that the client never is aware of the username or password of the resource owner.

Key Terms

  • client_id/client_secret – These two values are what provide the client identity that is mentioned. Each caller of the API is given its own identity and secret that it uses to confirm its identity to the API.
  • refresh_token – A long-lived value that the client store, the refresh_token establishes the relationship between a specific client and a specific user.
  • access_token – A short-lived token that can be generated based on the refresh token. A value that is ultimately passed to the API to prove that this client is authorized to make API calls on the user’s behalf.

Why is OAuth a good idea?

Key Benefits for Customers

  • OAuth access_tokens have a definite lifetime. When you generate an access_token from your refresh_token, you are provided an “expires_in” value that gives the number of seconds this token is good for. This simplifies code over the current, inactivity-based session timeout.
  • OAuth is a standard authorization mechanism. Third-party libraries are out there to help you get started with OAuth.
  • Integrating with third-party partners is much smoother. With OAuth, you no longer must provide them a username/password to access the . Instead, you generate a refresh token that they hold to make their API calls. If you ever need to end the relationship, you can delete the refresh token by using the UI and be assured that they no longer are able to access your data.

Key Benefits for IBM

  • Clients having identity is important to IBM. IBM can now track which client application is making API calls in addition to which the user account is being used.
  • OAuth is a standard. Writing secure authentication/authorization code is hard to get right, and using a standard, well vetted process helps.
  • OAuth allows IBM to be more scalable. The stateless nature of OAuth allows IBM to implement infrastructure in a more scalable way, which provides all customers a better experience.

Authentication Method: OAuth 2.0 Granted Access

Use OAuth to post an HTTPS request.

OAuth 2.0 authentication allows you to POST an HTTPS request to our server that embeds an Access Token in the response. The request will include 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 above, provides you with an Access Token which has a set lifetime of 4 hours. From this point forward, all requests against our 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 will allow you to have longer term access when needed. You will not have to get the new Access Token nearly as often as you do with the JSESSIONID.


  1. Defining your API application


    1. As an Org Admin user within your Watson Campaign Automation organization, navigate to Organization Settings.
    2. Click to expand Application Account Access.
    3. Select Add Application.

      The next page will prompt you for the Name of the Application you are creating access for and a brief description.

    4. Enter a name and description that will easily identify which application is connecting to your data in the Watson Campaign Automation.

    5. After you click Add, you will be able to see your Client Id and Client Secret. You will want to securely embed these tokens within you application.

  2. Getting Refresh Tokens

    Associate a user to an application after setting up your application.

    Note: Refresh tokens do not expire unless the user’s access is revoked from the Organization’s Settings for that application. 

    About this task

    Once you set up your application and get your Client Id and Client Secret tokens, you will be ready to associate a user to that application. We connect users to the application so that we can apply our existing built-in security model as is defined for that user for the application that will be authenticating with OAuth.


    1. Click Add Account Access.

    2. Choose an Application and user Account from the dropdown and click Add.

    After the token is created, it is emailed to the user who created the User Application access request, and to the Principle Org admin.

  3. Getting Access Tokens

    Once you obtain your Client Id, Client Secret, and Refresh Tokens, you will be able to generate your own Access Tokens.

    Here is how you do it:

    You will be sending an HTTPS POST to our Watson Campaign Automation server, substituting the following parameters as is appropriate for your Org.

    Method: POST

    URL Endpoint: https://api[x].ibmmarketingcloud.com/oauth/token

    Header: Content-Type: application/x-www-form-urlencoded

    Body: grant_type=refresh_token

             client_id=watson campaign automation generated client Id

             client_secret=watson campaign automation client secret

             refresh_token=watson campaign automation refresh token


    Note: Replace [x] with your Pod number.


    After a successful submission, the response includes a new access token and the period it is valid.

    {‘access_token’:’53940d9d-f498-4bf2-8231-17f43a5509a0′,’token_type’:’bearer’,’refresh_token’:'{the refresh token you provided’,’expires_in’:14399}

    Once the Access Token is acquired, you can use this cryptic string value to invoke any of the XML or REST APIs. A newly generated Access Token is valid for 4 hours, and a new Access Token may be requested using the above process only after a previous Access Token has been valid for 3 hours.


    OAuth flowchart 

  4. Invoking the correct API

    To call any of the XML APIs using the OAuth security model, you will send a HTTPS POST to our XML API endpoint, substituting the following parameters as is appropriate for your Org:

    Method: POST

    URL Endpoint: https://api[x].ibmmarketingcloud.com/XMLAPI

    Header: Authorization: Bearer [replace with the value of your fully generated access token]

    Header: Content-Type: text/xml;charset=utf-8

    Body: <Your XML code/>

    Invoking the REST API

    To call any of the REST APIs using the OAuth security model, you will send a request using the appropriate method to our REST API endpoint, substituting the following parameters as is appropriate for your Org:


    URL Endpoint: https://api[x].ibmmarketingcloud.com/rest


    Content-Type: application/json

    Authorization: Bearer [replace with the value of your fully generated access token]

    Body: Your JSON payload

    Learn more on authenticating APIs with OAuth.

4 comments on"Getting Started with OAuth for Watson Campaign Automation"

  1. For future generations, the header information for including an authorization token in an XML API is correct. The documentation says:

    Header: Authorization: [replace with the value of your fully generated access token]

    It should actually be:

    Header: Authorization: Bearer [replace with the value of your fully generated access token]

    This is noted in the REST API documentation but not in the XML documentation – it’s requred for both

    • Hello Andrew,
      Thank you for the correction. I have updated this document and this info is now available.

      Thank you

  2. The top sections “What is OAuth?” and “Details” has exactly the same lines. So why don’t you remove the details section.

Join The Discussion

Your email address will not be published. Required fields are marked *