Getting started with OAuth

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 data. 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 are no longer able to access your data.

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 Acoustic Campaign 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.

Step One: Defining your API application

1. As an Org Admin user within your 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 Campaign.
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 your application.

Step Two: Get 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.

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.

Step Three: Get 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 Campaign Automation server, substituting the following parameters as is appropriate for your Org.

Method: POST

URL Endpoint: https://{see the following API URL table and add the URL for your pod}/oauth/token

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

Body: grant_type=refresh_token

client_id= campaign automation generated client Id
client_secret= campaign automation client secret
refresh_token= campaign automation refresh token

Results
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.

Step Four: 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-campaign-[xx]-[y].goacoustic.com/XMLAPI

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

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

Body:

Step Five: 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:

Method: GET/POST/PATCH/DELETE

URL Endpoint: https://api-campaign-[xx]-[y].goacoustic.com/rest

Header: Content-Type: application/json

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

Body: Your JSON payload