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

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
   3. In the Privileges section, click 

      Insert excerpt
      _privilege _privilege nopanel true

   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 

      Insert excerpt
      _property_settings _property_settings nopanel true

   6. 

   7. Insert excerpt
      _save _save nopanel true

       the changes
3. 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 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 

         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 role

   3. Insert excerpt
      _save _save nopanel true

       the changes
4. The setup should look similar to:
   1. 

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 Headers section, click 

   Insert excerpt
   _add_icon _add_icon nopanel true

   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

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

Create Authentication User

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. 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
   _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. Name: GenerateAPIToken
   3. In the Privileges section, click 

      Insert excerpt
      _privilege _privilege nopanel true

   4. Search for the privilege, Run Actions and drag it into the Privileges section of the Role 

      Insert excerpt
      _property_settings _property_settings nopanel true

   5. Search for the privilege, Use API Key and drag it into the Privileges section of the Role 

      Insert excerpt
      _property_settings _property_settings nopanel true

   6. 

   7. Insert excerpt
      _save _save nopanel true

       the changes
3. In the 

   Insert excerpt
   _user_group _user_group nopanel true

    section, click 

   Insert excerpt
   _user_group _user_group nopanel true

   1. 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
         _user _user name icon nopanel true

          icon and drag across your API Agent user into the Users section
      4. Click 

         Insert excerpt
         _save _save nopanel true

          the changes
4. Click back onto the GenerateAPIToken Role tab
5. Drag the APIUsers user group into the 

   Insert excerpt
   _user_group _user_group nopanel true

    section of the GenerateAPIToken Role

   1. Insert excerpt
      _save _save nopanel true

       the changes

Generate Authentication Token

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

   Insert excerpt
   _property_settings _property_settings nopanel true

3. In the Secret Key Details section, click 

   Insert excerpt
   _add_icon _add_icon nopanel true

   1. Name: APIKey
   2. Enabled: 

      Insert excerpt
      _toggle_on _toggle_on nopanel true

   3. Insert excerpt
      _save _save nopanel true

       the changes
   4. Secret: click 

      Insert excerpt
      _add_icon _add_icon nopanel true

      1. In the Secret field, paste the API Key you copied above

      2. Insert excerpt
         _save _save nopanel true

          the changes
         
4. In the Headers section, click 

   Insert excerpt
   _add_icon _add_icon nopanel true

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

5. Insert excerpt
   _save _save nopanel true

    the changes

3.13 Advanced Actionflows - Training ExerciseImage Added