In this lesson we will cover:
– How to create an API application
– How to create a custom Integration
Creating an API Application
Within Halo you can create an API Application and then a custom integration, in order to perform GET's, POST's, etc… to API Endpoints in your Halo.
For the purposes of this guide, the custom integration will be integrating with Halo, to do this, first head over to Configuration>Integrations>Halo API>Applications and click "New" on the top right:
Fig 1. Halo API module
Fig 2. View applications button
Read the below instructions before configuring your API Application:
Fig 3. New API application
Creating an API Only Agent:
In Halo, navigate to Configuration > Teams & Agents > Agents and create an Agent that you will use for the integration.
Make sure the Agent has the Administrator Role, as displayed above.
It is also important to turn on API-only Halo Agent (This is found just below the roles input on the details tab of an agent (Beware that API-only Agents may not log into the Web or Mobile Applications nor can they be assigned tickets. However, they do not take up a licence). 
Now Input the following Into your API Application
- Name (arbitrary – typicall named Halo Instance, Own Instance, or something similar to this)
- Client ID and Secret (Note: The Client ID may change after saving, make sure to take the latest value)
- Generate (Generates a new client secret, must be done when creating a new custom integration)
- Copy (Copies the client secret to clipboard)
- Login Type: Agent
- Agent to log in as (Pick an agent)
- Permissions:
Fig 6. Permissions for API application
Creating a Custom Integration
The next step is to create a new custom integration in Configuration>Integrations>Custom Integrations, this is how the Halo instance is connected to the runbook and how the API can be used to GET or POST things in halo.
Fig 7. Custom Integrations button
The following credentials should be set:
Fig 8a. Example Credentials
Fig 8b. Example Credentials
Input the following:
- Base Resource URL: Your Halo instance URL i.e. https://[Your Halo Domain].com
- Authorization: OAuth 2.0
- Authorization header name *LEAVE BLANK*
- Header Prefix: Bearer (Should already appear as "Bearer")
- Grant Type: Client Credentials
- Access Token URL: https://[Your Halo Domain].com/auth/token?tenant=[Your Tenant Name], The tenant_id can be found by going to:
- https://[Your Halo Domain].com/api/instanceinfo (look for the key value pair "tenant_id" : "[Your tenant_id]" )
Found here (Other information has been blanked):
Fig 9. Tenant info example
- Client ID (Found in the Halo API Application created)
- Client Secret (Need to paste it from clipboard) NB: If the custom integration doesn't work when saving, you may need to input a new client secret by generating a new one in the Halo API application
- Scope: all
Creating a Method
Switch to the "Method" Tab on the custom integration and this should be the view:
Fig 10. Method
This worked example is for creating a runbook that returns a list of clients on a Halo instance. In the text box beside the Halo domain, input /api/client:
Fig 11. GET method
In the above photo the name of the method is "Get Clients" and the API method has been set to "GET"
The next thig to do is set the output variables, again solely for this example the output variable is:
Fig 12. Output variables
"response" must be the prefix of all output variable values that are inputted. This "Value" shown above translates to access the response of the GET on the clients, then get all of the properties of type clients within that GET, the "^" refers to a child property of an object.
Fig 13. Output variable example
Integration Runbooks
Now that the custom integration is set up and there is authentication into your Halo API. The next step is to create runbooks to automate your processes.
