Why Use Authentication?

Authentication is a way to verify that only permitted calls to an API are allowed.

Enabling Authentication on an API End Point

1. Open the API End Point
2. On the toolbar click  Properties
3. Disable  Allow Anonymous Connection 
   1. This will then only allow authenticated calls to the API
4.  Apply the changes

Creating Authentication Users

1. In the  Repository, expand the application with the Incoming API
2. Expand  Roles and create an New Role by clicking 
   1. Pin the tab as we will need it to remain open
   2. Provide a useful Name, e.g. GenerateToken
   3. In the Privileges section, click  Privileges
   4. Search for the privilege in the Full Repository : Use API Key
   5. Drag the Use API Key into the Privileges section of the Role  Properties
   6. 
   7.  Apply the changes
3. In the  User Groups section, click  User Groups
   1. Add a new Group for your Role
      1. Give it a useful Name e.g. API Users
      2. Add any users you require to be able to run the API. This could be a dedicated API user with limited privileges
         1. To create a user see Managing User Accounts → Creating Users
      3. Click  Apply and close the tab
   2. Now drag the new user group into the  User Groups section of the new role
   3.  Apply the changes
4. The setup should look similar to:
   1. 

Authentication Token KeyStore

A signing key is used to generate the PhixFlow API key and this is stored on the server to ensure secure access.

Using the page Configure a Keystore and Aliases, configure phixflow-api-key to be used as the signing key for PhixFlow API Keys in the same way as the pepperKey is configured. This secret string must be a minimum of 32 bytes length.

Generating Authentication Tokens

1. The Incoming API will run as a specified user, this means that when it is called the audit trail will show the specified user as having performed the Incoming API Actionflow
2. You do not need to login as this user, however, if you were already logged in as this user, you will need to logout and login again to pick up the user group change 
3. In the  Repository, scroll down to the Full Repository section and expand it
4. Expand the  Users section
5. Double click on the user who will run the Incoming API
6. Click the 3-dot more menu in the top right of the user properties
7. Click Generate API Key
8. Copy the value displayed and store it somewhere safe

Sending Authorisation

When calling the Incoming API, the authorisation token must be passed in as a header called: Authorization.

1. In the Headers section, click 
   1. Name: Authorization
   2. Expression: ${_datasource.APIKey}

Worked Example

Here's a worked example using the Company Data (available from the Learning Centre).

In this example, we are using:  

• A Company Call API screen containing a fixed drop down list of industries, a string fields for the API Status and a multi-line string field for the Results - this screen was created using the Tile with Buttons template

Add Authentication to API Calling Actionflow

In this example, we'll add authentication to the Actionflow that calls an API. 

Prerequisites

For this example, we'll modify an API End Point Actionflow containing company data to only allow authenticated calls and we'll add secret key details to an Actionflow that calls the API.

The two Actionflows that will be modified were created in 3.11 Setting up an API Endpoint. If you have not completed this chapter, expand the section below and follow the steps to create the Actionflows.

Enable Authentication on API End Point Actionflow

1. Open the API Company Data API End Point
2. On the toolbar click  Properties
3. In the API section, disable  Allow Anonymous Connection 
   1. This will then only allow authenticated calls to the API
4.  Apply the changes

Create Authentication User

1. In the  Full Repository, expand the  Users section 
2. Click  to create a new user who will be able to run the API
   1. Login: apiagent
   2. First Name: API
   3. Surname: Agent
   4. Password: Phixflow123!
   5. Enabled: 
   6.  Apply the user

Create Role

We need to create a role then assign the privilege and user group(s) to it.

1. In the  Repository for the application (not the full repository), expand the application you're working in
2. Expand  Roles and create an New Role by clicking 
   1. Pin the tab as we will need it to remain open
   2. Name: GenerateAPIToken
   3. In the Privileges section, click  Privileges
   4. Search for the privilege, Use API Key and drag it into the Privileges section of the Role  Properties
   5. 
   6. Search for the privilege, Run Actions and drag it into the Privileges section of the Role  Properties
   7.  Apply the changes
3. In the  User Groups section, click  User Groups
   1. Create a new User Group by clicking the 
      1. Name: APIUsers
      2.  Apply the new user group
      3. On the User Group, in the Users section, click  icon and drag across your API Agent user into the Users section
      4. Click  Apply the changes
4. Click back onto the GenerateAPIToken Role tab
5. Drag the APIUsers user group into the  User Groups section of the GenerateAPIToken Role
   1.  Apply the changes

Generate Authentication Token

1. In the  Full Repository, expand the  Users section
2. Double click on the API Agent user
3. Hover over the 3-dot more menu in the top right corner
4. Click Generate API Key
5. Copy the value displayed and store it somewhere safe

Send Authorization

1. On the screen, Company Call API, open the Actionflow on the Call API button
2. Click on the HTTP Action, Call API, to open its  Properties
3. In the Secret Key Details section, click 
   1. Name: APIKey
   2. Enabled: 
   3.  Apply the changes
   4. Secret: click 
      1. In the Secret field, paste the API Key you copied above
      2.  Apply the changes
         
4. In the Headers section, click 
   1. Name: Authorization
   2. Expression: ${_datasource.APIKey}
5.  Apply the changes

3.01 Bulk Delete Action Configuration