Skip to main content
This guide walks you through creating a dedicated role and API-only agent in Halo PSA for the MSPortal.ai integration. Use the permission tables below as the checklist for the role, then link the agent to the MSPortal API application.

​
Prerequisites

  • Administrator access to your Halo PSA instance
  • Access to the Configuration area in Halo PSA
Creating a dedicated MSPortal role and API-only agent is recommended for security best practices. This ensures the integration has only the permissions it needs and provides clear audit trails.

​
Create the MSPortal Role

1

Navigate to Agent Roles

In Halo PSA, go to Configuration → Teams & Agents → Roles.Navigate to Roles
2

Create New Role

  1. Click New
  2. Enter MSPortal as the role name
  3. Click Submit
3

Configure Role Permissions

Under the Permissions section, configure the following settings:
All configuration permissions should be set to Not set (disabled). The MSPortal integration does not require configuration access.
Role Permissions
4

Save the Role

Click Submit to save the new role.

​
Create the API-Only Agent

1

Navigate to Agents

Go to Configuration → Teams & Agents → Agents.Navigate to Agents
2

Create New Agent

  1. Click New
  2. Enter MSPortal as the agent name
  3. Check Is an API-only Agent
  4. Select MSPortal from the Role dropdown
API-only agents don’t require a password or email address since they’re used exclusively for API access.
3

Save the Agent

Click Submit to create the agent.

​
Assign Departments and Teams to the Role

This step is required for the MSPortal integration to access tickets, customers, and other data. The API agent will only be able to see data from departments and teams assigned to the role.
1

Open the MSPortal Role

Go to Configuration → Teams & Agents → Roles, then click on the MSPortal role to edit it.
2

Navigate to Departments & Teams Tab

Click on the Departments & Teams tab within the role settings.
3

Add Departments and Teams

Add all the departments and teams that you want MSPortal to have access to:
  1. Add each department whose data should be visible in MSPortal
  2. Add each team whose tickets and data should be visible in MSPortal
  3. Click Submit to save the role
If you skip this step, the MSPortal integration may not be able to see tickets, customers, or other data associated with those departments and teams.
1

Open API Applications

Navigate to Configuration → Integrations → Halo PSA API → View Applications.
2

Open the MSPortal Application

If you already connected MSPortal, open the MSPortal.ai application. Otherwise click New, name it MSPortal.ai and choose Client ID and Secret (Services) as the authentication method.
3

Select the Agent

In the Agent to Log in as dropdown, select the MSPortal API-only agent you just created.
4

Grant the API Permissions

Open the application’s Permissions tab and grant the permissions below. The role controls what the agent can do in Halo. These permissions control which parts of the API MSPortal can call.To create tickets, notes and time entries from MSPortal, also grant Ticket Modify. To manage Halo projects from MSPortal, also grant Project Read and Project Modify (see Project Management below).
5

Save and Copy the Credentials

Click Submit. For a new application, copy the Client ID and Client Secret now, because Halo shows the secret only once.

​
Check Permissions in MSPortal

1

Open the Halo PSA Setup

In MSPortal, go to Settings → Integrations → Halo PSA. For a new connection, enter your Halo URL, Client ID and Client Secret, then click Test Connection. The full walkthrough is in Connect Halo PSA.
2

Review the Permissions Step

Each required check must pass before you can continue. Optional checks that fail only turn off that feature.
3

Fix and Re-check

If a check fails, grant the permission it names in Halo, save, then click Re-check in MSPortal.
The Permissions step tests read access. Confirm write actions, like creating a ticket or logging time, by trying them once on a test record.

​
Project Management

Skip this section unless you will create or update Halo projects from MSPortal.
1

Grant Project and Ticket Access on the Application

On the MSPortal.ai application, grant Project Read, Project Modify, Ticket Read and Ticket Modify.
2

Confirm the Agent's Ticket Permissions

The Tickets permissions in the role table above cover child tickets, notes, time and to-do items. Make sure the agent’s teams, clients and ticket types include your project ticket types.
3

Test on a Project

Create a test project from MSPortal, add a note with time and complete a checklist item. The project management permission table lists each operation and current Halo limits.

​
Troubleshooting

The agent can only see data from the departments and teams on its role. Add them on the role’s Departments & Teams tab, and confirm Allow use of all Ticket Types and Allow use of all Customers are set. Then select Re-check on the MSPortal Permissions step.
Grant the matching application permission from the table above only if you want that feature. Otherwise leave its sync turned off.
A timeout is not a permission denial. Retry before changing the role.

​
Next Steps

Return to the Halo PSA setup in MSPortal to choose what to sync and map your Halo customers to MSPortal companies.

Configure Halo PSA Integration

Complete guide to connecting Halo PSA with MSPortal.ai