HaloCRM

HaloCRM Guides

Guides > Creating API Applications

Creating API Applications

In this guide we will cover:

- API Details

- Application Configuration



Related Guides:


This guide outlines the configuration of Halo applications which can be used to connect applications to your instance of Halo via the API.


API Details

Navigate to Configuration > Integrations > Halo API to see the related configuration page. This area provides details about connecting to your instance of Halo via the API including resource and authorization servers as well as a link to our official API documentation.


Fig 1. API details.


Documentation about your Halo API can also be found at <Halo Web App Agent Portal URL>/api/swagger.


You are also able to connect to other instances of Halo utilizing the "Connected Instances" area.


Application Configuration

From this page, click "View Applications" to find your list of Halo applications. Note that there are previously configured applications which are used to connect various aspects of your Halo Web App. Please do not adjust any of these existing applications as they are vital in the basic function of your instance of Halo.


From v2.218+, the Agent to log in as will show here. 

Fig 2. List of applications.


To start a new application, click "New" on the top right corner of the screen. 


From here on the "Details" tab, you will be prompted to name your application, enable it, and set its "Authentication Method". From v2.218+, you can include a description here, and upon creation a "Creation Date" and "Created By" field will auto populate.


Fig 3. Configuring the application.


Authentication Methods

  • The following authentication methods are available for Halo API applications:
  • Username & Password
  • Implicit Flow (Single Page Application)
  • Authorisation Code (Native Application)
  • Client ID and Secret (Services)
  • API Key (v2.212.1+) (This should only be used if the system you are integrating with does not offer one of the other OAuth flows)


For example, we can set our application to "Client ID and Secret (Services)" and we are provided a "Client ID" and "Client Secret" which we can utilize in another application to connect to your instance of Halo. We are also prompted to select a "Login Type" and setting specific to that login type.


Using Machine Identity (v2.214+)

From v2.214+ when using a Client ID and Secret (or API Key) to authenticate you will be able to give the application a machine identity rather than having to have the application log in as (use the identity of) a specific agent. 


This allows the application to not act as particular agent. This means it's access will not be tied to the access/permissions of a particular agent. Useful for auditing changes as it will be clear what changes actual agents have completed vs changes the application completes. Making it easier to restrict the application's permissions and follow the principle of least privilege. 


To do this set the "Agent to log in as" as "Application identity". 

Fig 4. Create application to authorise using a machine (application) identity. 


Once chosen you will be able to give the application "Identity Roles". The role chosen here will determine what the application has permission to do in your instance. The roles available here will be determined by the agent roles you have created in your instance, however the "sys-all-permissions" role will also be available. 


sys-all-permissions - This role grants highest levels of access, access will then be filtered down based on selected scopes.


Require JWT Assertion - Client ID and Secret method only (v2.218+)

From v2.218+ JWT assertions can be added as a requirement for API applications using the Client ID and Secret authentication method. This adds additional security to applications, it is not necessary most of the time but it is recommended for applications with high privileges.  

Fig 5. Enable the requirement of JWT assertion to authenticate an application.


When used, you will need to generate a JWT, this will need to be signed with a RSA private key using the PS256 algorithm. The Halo server will then validate the JWT supplied the in the "client_assertion" property, using the known public key. 


Once the application authorisation is set you can give the application scopes/permissions. 


Give the Application Permissions/Scopes

On the "Permissions" tab you are able to set exactly what services utilizing this application are able to do in Halo. If the application is authenticating access as a particular agent, or has been given it's own roles, these permissions will apply in addition to the agent/role restrictions. Permissions will further filter down what the application is able to do. 



Fig 6. Permission options.


Simply check the permissions/scopes you would like the application to have. 

Popular Guides

Pin It on Pinterest