How to enable Frends Platform API

The Platform API is not active out of the box, and must be set up before it can be used. Currently the API uses only external authentication methods that you need to provide, setting the authentication up is requirement to using the Platform API.

Setting up the authentication

The Platform API uses Bearer Token authentication. The Bearer Token is created for you by the authentication server that needs to be separately added by contacting Frends support. Currently only Azure Active Directory (AAD) is supported. You can follow these instructions to create the app registration in AAD.

Sign in to your AAD environment, and navigate to App registrations and select New registration.

Give the application a name, and from Supported account types select Accounts in this organizational directory only (Single tenant). You can leave the redirect URI empty.

Next, navigate to Expose an API section and select Add Application ID URI. This will generate an Application ID URI for you. Click Save at the bottom of the view.

Next, we need to create an app role for the application. The application we created defines and publishes the app roles and interprets them as permissions during authorization. This is the reason why we need to create an Administrator app role for the application user so that we can access the Platform API.

Navigate to App roles and click on Create app role. Enter these values:

• Display name: Admin

• Allowed member types: Applications

• Value: Administrator

• Description: Admin

Remember to check that "Do you want to enable this app role?" is enabled.

Now, navigate to Certifications & secrets and add a new client secret. You can leave the description empty. Copy the value when it has been created, and store it in a safe location. This will be needed later and is not easily accessible afterwards.

Finally, go to API permissions and add new permission. Select APIs my organization uses and select the app you just created. Check the box Administrator. Finish the permission by selecting Grant admin consent. Without admin consent you are able to fetch the access token, but further Platform API requests will fail with unauthorized exception error.

After that you are all set. Navigate to the Overview page and collect information from there for the subscription of the application to Frends Support. The information needs to be in JSON format, like shown below.

Put every public IP address with a subnet mask where the Platform API is to be used from, for example your Frends Agents' static IP addresses. The specified machines will be the only places that can make requests to Platform API.

{
    "allowedIps": [
        {
            "ipAddress": "0.0.0.0",
            "subnetMask": "255.255.255.255"
        },
        {
            "ipAddress": "0.0.0.0",
            "subnetMask": "255.255.255.255"
        }
    ],
    "audience": "<Application ID URI>",
    "tenant": "<tenant-name>.onmicrosoft.com"
}

Send this information to Frends Support and they will set up and enable the authentication for the Platform API.

Using the Platform API

Once the AAD App registration is done and authentication is set up, it's possible to start using the API.

Before actual requests can be made into the API, a bearer token must be obtained from AAD.

Use the following parameters in a HTTP Request Task to fetch the token. The examples assume the values have been saved as Environment Variables, except for the URL. All the values used in the Message are from setting up the authentication, while the Url is dependant on your AAD tenant's name.

• Task type: HTTP Request

• HTTP method: POST

• Result method: JToken

• Url: https://login.microsoftonline.com/<AAD tenant>.onmicrosoft.com/oauth2/token

• Message: client_id={{#env.ManagementAPI.ApplicationId}}&client_secret={{#env.ManagementAPI.ClientSecret}} &grant_type=client_credentials &resource={{#env.ManagementAPI.ApplicationURI}}

• Authentication: None

After fetching the token, you can create requests to the Platform API using another HTTP Request Task and using the obtained token as OAuth token.

As an example, here are the Task details for requesting a list of Processes from your Tenant.

• Task type: HTTP Request

• HTTP method: GET

• Result method: JToken

• Url: https://yourtenant.frendsapp.com/api/v1/processes

• Authentication: OAuth

• Token: #result[HTTP Request Fetch Token].Body.access_token

As long as the Agents in your Frends Tenant were whitelisted by their IP successfully, this Process can be used to test the functionality of the Platform API in your Tenant. If the development Agent Group's Agents were not whitelisted, you may need to deploy the Process to another Agent Group first.

If you whitelisted other IP ranges than for your Frends Agents, you can also go and perform these HTTP Requests using Postman, for example, and you should obtain the same result.