Introduction

Poppulo uses industry standard OAuth for authorization. All of our GraphQL APIs are secured using OAuth meaning you need a valid Access Token before you can use our service. This document will equip you with the understanding required to get valid Access Tokens.

What's Supported

Whilst OAuth defines a number of different Authorization flows Poppulo currently only supports the client credentials flow. This allows for Machine to Machine interactions with our services.

Client Credentials Flow

The Client Credentials flow is the simplest of the OAuth flows and is used to identify the calling service. This flow is best suited for Machine to Machine applications such as backend services.

OAuth is a mature standard with many tools that support the Client Credentials flow, OAuth maintains a list of packages for covering more than just Client Credentials:

• https://oauth.net/code/

The following sequence diagram illustrated the process for requesting an Access Token from an Authorization server and using the resulting Access Token:

How to obtain Client Credentials

In order to create an API Client you MUST have a Comms XP Licence and the Enterprise Administrator role, this will give you access to the API Client Section within the Integration Manager.

Navigating to Integration Manager -> API Clients

Once you are logged into the Employee Communications Application, starting at the Dashboard, select the "Integrations Manager" Tile:

You’ll now see a UI like the following, you now need to select the API Clients section on the left:

You’ll now see a UI like the following, by clicking on the "+ Create" button you can build your Client and get your Client Credentials:

Creating the API Client

Once you have navigated to the Integration Manager -> API Clients you are now ready to create a new API Client. To start the process click the "+ Create" button in the top right and you should see a dialog like the following:

Fill in your chosen Client Name & Description, then click next:

Select your required permissions, click save then next:

You now have a chance to review your selection and if you are happy with your selection click create:

At this stage your client has been created and you will need to copy the Client ID & Secret to a secure location for use by your application.

How to obtain an Authorization Token

Use the client credentials to request a token and use that token to call our GraphQL APIs as described in Getting Started. As previously stated OAuth maintains a list of packages on a per language basis to support your authorization requirements, you should evaluate these options and follow your chosen packages Client Credentials flow instructions:

• https://oauth.net/code/

If you are unable to use an existing package to get your authorization token using your Client Credentials, the following curl can be used to make a Standard HTTP Request for them:

Poppulo provides two geo specific GraphQL endpoints for Authorization. One is for US hosted customers and the other for EU hosted customers. Use the endpoint based on the location of where the Poppulo account is hosted to fill in the TOKEN_URL value. If you are uncertain as to which endpoint to use please contact your account manager.

• https://iam.eu2.poppulo-app.com/oauth/v2/oauth-token
• https://iam.us2.poppulo-app.com/oauth/v2/oauth-token

TOKEN_URL="placeholder"
CLIENT_ID="placeholder"
CLIENT_SECRET="placeholder"

curl -s -X POST "$TOKEN_URL" \
    --header "Content-Type: application/x-www-form-urlencoded" \
    -d "grant_type=client_credentials" \
    -d "client_id=$CLIENT_ID" \
    -d "client_secret=$CLIENT_SECRET"

You will receive a value like the following, you will need to save the $.access_token value and use that in your AUTHORIZATION header:

{"access_token":"_0XBPWQQ_5d1fab6b-c975-4313-ac3e-bf12c8893518","scope":"","token_type":"bearer","expires_in":300}

In this example the token will expire in 300 seconds (5 mins), you will need to generate a new token before the token expires.