HaloPSA
      Back to home
      1. Help Center
      2. Connect TopLeft to Your PSA
      3. HaloPSA

      Configure HaloPSA Role and API Agent

      How to set up HaloPSA for TopLeft

      TopLeft needs access to your HaloPSA application to download tickets, projects, members, and other records used to display your data. It also updates Halo records when changes are made in TopLeft.

      All communication between TopLeft and Halo uses the HaloPSA REST API and is encrypted by TLS.

      To allow TopLeft access to your Halo data, follow these instructions. These steps must be performed by a Halo administrator with permission to manage roles and API settings.

      Setup Checklist

      These are the steps to configure HaloPSA for TopLeft:

      1. Add a role for TopLeft
      2. Add an API Agent
      3. Add an API Application
      4. Submit the API credentials and other information in the customer portal

      Add a Role for TopLeft

      To limit the information available to TopLeft, we recommend you set up a Role dedicated to the TopLeft user. To open the Roles administration section, click Configuration > Teams & Agents (in Core Features) > Roles.

      Click New and create a role called "TopLeft Role". Save it, then edit the permissions on the Permissions tab. In the General Permissions section, set "Is a HaloPSA Administrator" to Yes.

      TopLeft needs this administrator setting because it's needed for access to the Agents API. TopLeft permissions will be restricted to a lower level in the application scope setup below.

      Save the role.

      Add an API Agent

      Now create the agent for TopLeft, using the Role you created above.

      Navigate to Configuration > Teams & Agents > Agents. Click New and set up the agent as follows:

      • Username: topleft
      • Roles: TopLeft Role
      • Account Active: checked
      • Is an API-only Agent: checked
      • Default Team: No Default Team
      • Work Hours: Default Working Hours

      Save the agent.

      Add an API Application

      Navigate to Configuration > Integrations (in Advanced) > HaloPSA API (in Featured).

      Make note of the "Resource Server" and "Authorisation Server" URLs. You will submit these to TopLeft in a later step.

      On the HaloPSA API page, under Applications, click View Applications.

      Click New and set up the application as follows:

      • Details tab:
        • Application Name: TopLeft
        • Authentication Method: Client ID and Secret (Services)
        • Login Type: Agent
        • Agent to log in as: topleft
        • Make note of the Client ID and Client Secret. You will submit them to TopLeft. The Client Secret will not be shown again. If you lose the secret, you can regenerate a new one.
      • Permissions tab- select these options:
        • all:standard
        • all:teams
        • admin:webhooks

      Save the application.

      Submit the API Credentials and Other Information in the Setup Portal

      Go to https://customers.topleft.team/welcome/ and enter the requested information, including these API credentials.

      That's it! Your application will be configured when you submit your information, and you'll get an email with instructions for logging in the first time.

      Troubleshooting

      If you have trouble setting up permissions, try these steps:

      1. Double-check the role permissions against the list above. The permissions required by TopLeft can change as we introduce new features and as Halo updates their schema.

        After your TopLeft app has been set up, you can use a tool in the app to check permissions. It is available in Settings > HaloPSA API > Check Permissions.
      2. Delete the TopLeft role, then create a new one from scratch as per the steps above. Then set the API agent's role to the new role.

      Further Reference

      Refer to HaloPSA documentation: