Adding Authentication to an API End Point

Step 1 - Enable Authentication

Why Use Authentication?

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

How To Enable Authentication on an API Endpoint

1. Open a 

   Insert excerpt
   _actionflow_api_endpoint _actionflow_api_endpoint name text nopanel true

    in PhixFlow from the 

   Insert excerpt
   _actionflow _actionflow nopanel true

    homepage
2. On the toolbar, click 

   Insert excerpt
   _property_settings _property_settings nopanel true

3. In the API section, disable Disable 

   Insert excerpt
   _toggle_off _toggle_off nopanel true

    Allow Anonymous Connection 
   1. This will then only allow authenticated calls to the API

4. Insert excerpt
   _save _save nopanel true

    the changes

How To Create

Authentication Users

Create New User (Optional)

Create a dedicated API user with limited privileges if you want the API to show as being run by this user in the System Console. 

1. In the 

   Insert excerpt
   _repository _repository name full nopanel true

   , expand the 

   Insert excerpt
   _user _user nopanel true

    section 
2. Click 

   Insert excerpt
   _add_icon _add_icon nopanel true

    to create a new user who will be able to run the API
   1. Enabled: 

      Insert excerpt
      _toggle_on _toggle_on nopanel true

   2. Insert excerpt
      _save _save nopanel true

       the user

Create New Role

1. In the

   Insert excerpt
   _repository _repository nopanel true

   , expand the application with the Incoming API
2. Expand

   Insert excerpt
   _roles _roles nopanel true

    and create an New Role by clicking 

   Insert excerpt
   _addIcon _addIcon nopanel true

   1. Pin the tab as we will need it to remain open
   2. Provide a useful Name, e.g. GenerateToken

Add Privileges to New Role 

1. In the Privileges section, click 

   Insert excerpt
   _privilege _privilege nopanel true

2. Search for and drag across the privilege following privileges in the Full Repository Repository: 
   • Use API Key
   • Run Actions
3. Drag the Use API Key into the each privilege across from the Full Repository into the Privileges section of the Role 

   Insert excerpt
   _property_settings _property_settings nopanel true

   Image Removed

4. Insert excerpt
   _save _save nopanel true

    the changes

Create and Assign API User Group to Role

1. In the 

   Insert excerpt
   _user_group _user_group nopanel true

    section, click 

   Insert excerpt
   _user_group _user_group nopanel true

   1. Add a new Group for you 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.
         1. This could be a dedicated API user with limited privileges
         2. To create a user , such as the one created in the section, Create New User, above
            1. For more on creating users, see Managing User Accounts
             → Creating Users
      3. Click 

         Insert excerpt
         _save _save nopanel true

          and close the tab
   2. Now drag the new user group into the 

      Insert excerpt
      _user_group _user_group nopanel true

       section of the new privilegerole

   3. Insert excerpt
      _save _save nopanel true

       the changes
2. The setup should look similar to:
   1. Image Removed

Step 3 - 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.

1. 1. Image Added

Assign Application Access User Group to New User (Optional)

1. If you created a new user, in the 

   Insert excerpt
   _repository _repository name full nopanel true

   , expand the

   Insert excerpt
   _user _user nopanel true

    section
2. Double click on the new user
3. In the User Groups section, click the 

   Insert excerpt
   _user_group _user_group name icon nopanel true

    icon to display the available User Groups in the Full Repository
4. Search for the name of your application in the search box
   1. Two User Groups will display - drag across the one that doesn't contain _Admin into the User Group section of your user

How To Generate 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 

   Insert excerpt
   _repository _repository nopanel true

   , scroll down to the Full Repository section and expand it
4. Expand the

   Insert excerpt
   _user _user nopanel true

    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

How To Send Authorisation

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

1. On the 

   Insert excerpt
   _http _http nopanel true

    action, open the 

   Insert excerpt
   _property_settings _property_settings nopanel true

2. In the Secret Key Details section, click 

   Insert excerpt
   _add_icon _add_icon nopanel true

   1. Give the secret key a name, e.g. MyAPIKey
   2. Toggle on Enabled

   3. Insert excerpt
      _save _save nopanel true

       the secret key
   4. Next to Secret, click 

      Insert excerpt
      _add_icon _add_icon nopanel true

   5. Paste in the API Key you copied above - see above section, How To Generate Authentication Tokens

   6. Insert excerpt
      _finish _finish nopanel true

       the Local Secret and Secret Key
3. In the Headers section on the

   Insert excerpt
   _http _http nopanel true

    action, click 

   Insert excerpt
   _add_icon _add_icon nopanel true

   1. Name: Authorization
   2. Expression: ${_datasource.MyAPIKey}
      1. Where MyAPIKey is the name of the Secret Key you set above

Worked Example

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

In this example, we are using:  

• A Company Orders screen containing two grids of the Orders and OrderLines data - this 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 Multi-tile  Tile with Buttons template

Add Authentication to API Calling Actionflow

In this example, we'll create an Actionflow to import the AdditionalCompanies_Processed data and add the Status of New to each company on that table before adding it to the Companies table. We'll add this Actionflow to an Exclusion Group with other Actionflows on the same screen so that other processes cannot be triggered while the import is taking place.

Image Removed

Actionflow Setup

add authentication to the Actionflow that calls an API. 

Image Added

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

   Insert excerpt
   _actionflow_api_endpoint _actionflow_api_endpoint nopanel true

    API Company Data 
2. On the toolbar click 

   Insert excerpt
   _property_settings _property_settings nopanel true

3. In the API section, disable 

   Insert excerpt
   _

   action

   toggle_

   calculate

   off _

   action

   toggle_

   calculate

   off nopanel true

    action to the canvas and connect  Allow Anonymous Connection 
   1. This will then only allow authenticated calls to the API

4. Insert excerpt
   _save _save nopanel true

    the changes

Create Authentication User

1. In the 

   Insert excerpt
   _repository _repository name full nopanel true

   , expand the 

   Insert excerpt
   _

   input

   user _

   input

   user nopanel true

    node to it
2. On the Calculate action, add the following Output Attribute that will be used to update the Status of all imported companies:
   1. Name: Status
      1. Type: String
      2. Expression: "New"
3. On the Calculate action, add another Output Attribute that will be used to add a 20 second delay into the Actionflow, this will simulate a large data import and allow time to trigger the Actionflow twice:
   1. Name: Delay
   2. Type: Integer
   3. Expression: sleep(20)
      1. This will add a delay into the Actionflow for demonstration purposes. See sleep
4. Add a  section 
5. Click 

   Insert excerpt
   _add_icon _add_icon nopanel true

    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: 

      Insert excerpt
      _toggle_on _toggle_on nopanel true

   6. Insert excerpt
      _save _save nopanel true

       the user

Create Role

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

1. In the

   Insert excerpt
   _repository _repository nopanel true

    for the application (not the full repository), expand the application you're working in
2. Expand

   Insert excerpt
   _

   action_analysis_action_analysis

   roles _roles nopanel true

    and create an New Role by clicking 

   Insert excerpt
   _addIcon _addIcon nopanel true

    action to the canvasOn its Properties
   1. Pin the tab as we will need it to remain open
   2. Name: GenerateAPIToken

Add Privileges to Role

1. On the Role, in the Tables Privileges section, click the click 

   Insert excerpt
   _

   tables

   privilege _

   tables

   privilege

   nameicon

   nopanel true

    icon
   1. Drag across the AdditionalCompanies_Processed table from the Repository to the Analysis action properties

   Connect the Calculate action to the Analysis action and map across the attribute

   Expand
   title Checkpoint
   Image Removed

Table Attributes Setup

1. On the Analysis Model, Actionflow Advanced Data, click on the table, AdditionalCompanies_Processed
2. Double-click on the attribute, Status, and change the Expression to _context.Status
   1. This is then referring to the attribute setup on the Calculate action
3. Save the Analysis Model

Combine Data & Display 

1. On the Actionflow, create a 
   1. Search for and drag across the following privileges from the Full Repository into the Privileges section of the Role 

      Insert excerpt
      _property_settings _property_settings nopanel true

      :
      • Run Actions
      • Use API Key
   2. Image Added

   3. Insert excerpt
      _save _save nopanel true

       the changes

Create and Assign User Group to Role

1. On the Role, in the 

   Insert excerpt
   _user_group _user_group nopanel true

    section, click 

   Insert excerpt
   _actionuser_viewgroup _actionuser_viewgroup nopanel true

    action with the Primary Table, AdditionalCompanies_Processed, and connect the Analysis action to the View action
   1. In its Properties, in the Data Retrieval Options section, set the Data Range to Latest
      1. This will ensure that this data isn't continuously added if the Actionflow is run repeatedly
   2. For the Output Attributes section, click the Create a new User Group by clicking the 

      Insert excerpt
      _add_icon _add_icon nopanel true

      1. Name: APIUsers

      2. Insert excerpt
         _save _save nopanel true

          the new user group
      3. On the User Group, in the Users section, click

         Insert excerpt
         _

      attributes_icon_attributes_

      1. user _user name icon nopanel true

          icon and drag across
      all attributes
   Create a 
   1. 1. your API Agent user into the Users section
      2. Click 

         Insert excerpt
         _

   action_

   1. 1. save

   _action

   1. 1. _save nopanel true

    action to save the data to the Companies table
   1. In its Properties, in the Basic Settings section, set the Type to Insert and
      1.  the changes
2. Click back onto the GenerateAPIToken Role tab
3. Drag the APIUsers user group into the 

   Insert excerpt
   _user_group _

   toggle_on_toggle_on

   user_group nopanel true

    section of the GenerateAPIToken RoleOpen the Actionflow 

   1. Insert excerpt
      _save _save nopanel true

       toggle on Auto Save Attributes
   Connect the View to the Save action and map across all attributes

   Image Removed

   Expand
   title Checkpoint
   Image Removed

Setting the Exclusion Group

1. 1.  the changes

Assign Application Access User Group to User

1. In the 

   Insert excerpt
   _repository _repository name full nopanel true

   , expand the

   Insert excerpt
   _user _user nopanel true

    section
2. Double click on the API Agent user
3. In the User Groups section, click the 

   Insert excerpt
   _propertyuser_settingsgroup _property_settingsuser_group name icon nopanel true

    
   1. Under Basic Settings, populate the Exclusion Group field with any text, e.g. Import
   2. Image Removed

   Add the same Actionflow to the Import button the Company Management screen

   Expand

   title	How?

   On the ImportCompanies Actionflow, open the  icon to display the available User Groups in the Full Repository
4. Search for the name of your application in the search box
   1. Two User Groups will display - drag across the one that doesn't contain _Admin into the User Group section of your API Agent user

Generate Authentication Token

1. On the API Agent user, hover over the 3-dot menu in the top right corner
2. Click Generate API Key
3. Copy the value displayed and store it somewhere safe

Image Added

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

   Insert excerpt
   _property_settings _property_settings nopanel true

3. , hover over the In the Secret Key Details section, click 

   Insert excerpt
   _add_icon _add_icon nopanel true

   1. Name: APIKey
   2. Enabled: 

      Insert excerpt
      _

   more

   1. toggle_

   options

   1. on _

   more_optionsnameicon

   1. toggle_on nopanel true

   2. Insert excerpt
      _save _save nopanel true

    icon and choose 
   1.  the changes
   2. Secret: click 

      Insert excerpt
      _

   repository

   1. add_

   find

   1. icon _

   repository

   1. add_

   find

   1. icon nopanel true

4. Open the Company Management screen and drag the highlighted Actionflow from the Repository onto the Import button
   1. This will create another instance of the same Actionflow

Testing

1. Open the Company Approval Review and Company Management screens
2. Ensure both screens are 
   1. 1. In the Secret field, paste the API Key you copied above

      2. Insert excerpt
         _save _save nopanel true

          the changes
         Image Added
3. In the Headers section, click 

   Insert excerpt
   _add_icon _add_icon nopanel true

   1. Name: Authorization
   2. Expression: ${_datasource.APIKey}

4. Insert excerpt
   _locksave _locksave nopanel true

   ed
5. Click Import on one screen then press Import on the other screen
6. A warning message should appear

Image Removed

1.  the changes

Image Added

Testing

1. On the Actionflow calling the API, click Run Action and run the Actionflow
2. Access the System Console to check if the API displays as being run by your specific API User

Image Added

Image Modified