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. Using a custom role with specific permissions ensures a secure, least-privilege connection.

​
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.
If you’ve already created an API application for MSPortal.ai, update it to use your new agent:
1

Open API Applications

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

Edit MSPortal Application

Find the MSPortal.ai application you created during the initial integration setup.
3

Update Agent Assignment

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

Save Changes

Click Submit to save the updated application settings.

​
Next Steps

Your Halo PSA integration is now configured with a dedicated role and API-only agent. Return to MSPortal.ai to:
  • Test the connection in Settings → Integrations → Halo PSA
  • Configure sync settings for tickets and opportunities
  • Verify data is syncing correctly

Configure Halo PSA Integration

Complete guide to connecting Halo PSA with MSPortal.ai