> ## Documentation Index
> Fetch the complete documentation index at: https://docs.msportal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Custom Halo PSA Role and API User

> Set up a dedicated MSPortal role and API-only agent in Halo PSA for secure integration

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

<Info>
  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.
</Info>

## Create the MSPortal Role

<Steps>
  <Step title="Navigate to Agent Roles">
    In Halo PSA, go to **Configuration** → **Teams & Agents** → **Roles**.

    ![Navigate to Roles](https://colony-recorder.s3.amazonaws.com/files/2025-12-16/158beb82-87a4-4d6e-bd98-0d10ca022cb2/stack_animation.webp)
  </Step>

  <Step title="Create New Role">
    1. Click **New**
    2. Enter **MSPortal** as the role name
    3. Click **Submit**
  </Step>

  <Step title="Configure Role Permissions">
    Under the **Permissions** section, configure the following settings:

    <AccordionGroup>
      <Accordion title="General Permissions">
        | Permission                   | Setting |
        | ---------------------------- | ------- |
        | Is a HaloPSA Administrator   | Not set |
        | Editing of own Preferences   | Not set |
        | Editing of own Notifications | Not set |
      </Accordion>

      <Accordion title="Feature Access">
        | Module                     | Access Level                        |
        | -------------------------- | ----------------------------------- |
        | Tickets                    | **Read and Modify**                 |
        | Customers                  | **Read and Modify**                 |
        | Users                      | **Read and Modify**                 |
        | CRM                        | **Read and Modify**                 |
        | Assets                     | **Read, Modify and Delete**         |
        | Calendars and Appointments | **Read and Modify**                 |
        | Knowledge Base             | **Read, Modify and Delete**         |
        | Suppliers                  | **Read and Modify**                 |
        | Products                   | **Read and Modify**                 |
        | Sales                      | **Read and Modify**                 |
        | Quotations                 | **Read and Modify**                 |
        | Sales Orders               | **Read, Modify and Delete**         |
        | Purchase Orders            | **Read and Modify**                 |
        | Billing Details            | **Read and Modify**                 |
        | Invoices                   | **Read, Create, Modify and Delete** |
        | Reporting                  | **Read and Modify**                 |
        | Customer Agreements        | **Read and Modify**                 |
        | Supplier Agreements        | **Read and Modify**                 |
        | Service Catalogue          | **Read and Modify**                 |
        | Software Releases          | **Read and Modify**                 |
        | Timesheets                 | **Read and Modify (All)**           |
        | Software Licencing         | **Read and Modify**                 |
        | Segments                   | **Read and Modify**                 |
        | Documents                  | Not set                             |
        | Mail Campaign              | **Read and Modify**                 |
        | Event Management           | Not set                             |
      </Accordion>

      <Accordion title="Tickets Permissions">
        | Permission                                                    | Setting                  |
        | ------------------------------------------------------------- | ------------------------ |
        | Can add new Tickets                                           | **Yes**                  |
        | Can edit closed Tickets                                       | **Yes**                  |
        | Can view Unassigned Tickets                                   | **Yes**                  |
        | Can view Tickets assigned to other Agents                     | **Yes**                  |
        | Can change a Ticket's Ticket Type                             | **Yes**                  |
        | Can Re-assign Tickets                                         | **Yes**                  |
        | Can Edit Advanced Ticket Details                              | **Yes**                  |
        | Editing of Actions                                            | **Can Edit All Actions** |
        | Can manually adjust billing time allocation per action        | **All**                  |
        | Can recalculate billing against Tickets                       | **Yes**                  |
        | Can Delete Tickets                                            | **No**                   |
        | Can assign to Agents in Teams the Agent is not a member of    | **Yes**                  |
        | Can Edit Tickets Which Are Not Assigned To Them               | **Yes**                  |
        | Can override maximum priority escalation at ticket type level | **Yes**                  |
        | Can Override Ticket Review Processing                         | **Yes**                  |
        | Can use the Treat as Spam button                              | **Yes**                  |
        | Can export tickets                                            | **Yes**                  |
        | Can always update Ticket Statuses outside of actions          | **Yes**                  |
        | Can remove To-Do items                                        | **Yes**                  |
      </Accordion>

      <Accordion title="Calendars and Appointments Permissions">
        | Permission                 | Setting                         |
        | -------------------------- | ------------------------------- |
        | Editing of Appointments    | **Can Edit All Appointments**   |
        | Adding New Appointments    | **Can Add All Appointments**    |
        | Visibility of Appointments | **Can View All Appointments**   |
        | Deleting of Appointments   | **Can Delete All Appointments** |
      </Accordion>

      <Accordion title="Restrictions">
        | Restriction                   | Setting |
        | ----------------------------- | ------- |
        | Allow use of all Ticket Types | **Yes** |
        | Allow use of all Customers    | **Yes** |
        | Customer Group Override       | Not set |
        | Allow use of all Asset Types  | **Yes** |
        | Allow use of all Asset Fields | **Yes** |
      </Accordion>

      <Accordion title="Billing Permissions">
        | Permission           | Setting       |
        | -------------------- | ------------- |
        | Can View Item Costs  | **Read Only** |
        | Can View Item Prices | **Read Only** |
        | Can View Product SKU | **Read Only** |
        | Can View Agent Costs | **No**        |
      </Accordion>

      <Accordion title="Configuration Permissions">
        All configuration permissions should be set to **Not set** (disabled). The MSPortal integration does not require configuration access.
      </Accordion>
    </AccordionGroup>

    ![Role Permissions](https://colony-recorder.s3.amazonaws.com/files/2025-12-16/9cdf2e26-232a-49a1-bd24-88fc7be0a04b/stack_animation.webp)
  </Step>

  <Step title="Save the Role">
    Click **Submit** to save the new role.
  </Step>
</Steps>

## Create the API-Only Agent

<Steps>
  <Step title="Navigate to Agents">
    Go to **Configuration** → **Teams & Agents** → **Agents**.

    ![Navigate to Agents](https://colony-recorder.s3.amazonaws.com/files/2025-12-16/efce8d3a-7c8b-42e6-909f-b69bb70253bc/stack_animation.webp)
  </Step>

  <Step title="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

    <Tip>
      API-only agents don't require a password or email address since they're used exclusively for API access.
    </Tip>
  </Step>

  <Step title="Save the Agent">
    Click **Submit** to create the agent.
  </Step>
</Steps>

## Assign Departments and Teams to the Role

<Warning>
  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.
</Warning>

<Steps>
  <Step title="Open the MSPortal Role">
    Go to **Configuration** → **Teams & Agents** → **Roles**, then click on the **MSPortal** role to edit it.
  </Step>

  <Step title="Navigate to Departments & Teams Tab">
    Click on the **Departments & Teams** tab within the role settings.
  </Step>

  <Step title="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
  </Step>
</Steps>

<Info>
  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.
</Info>

## Link the Agent to Your API Application

<Tabs>
  <Tab title="Existing API Application">
    If you've already created an API application for MSPortal.ai, update it to use your new agent:

    <Steps>
      <Step title="Open API Applications">
        Navigate to **Configuration** → **Integrations** → **Halo PSA API** → **View Applications**.
      </Step>

      <Step title="Edit MSPortal Application">
        Find the **MSPortal.ai** application you created during the initial integration setup.
      </Step>

      <Step title="Update Agent Assignment">
        In the **Agent** dropdown, select the **MSPortal** API-only agent you just created.
      </Step>

      <Step title="Save Changes">
        Click **Submit** to save the updated application settings.
      </Step>
    </Steps>
  </Tab>

  <Tab title="New Integration Setup">
    If you haven't configured the Halo PSA integration yet, follow the complete setup guide. When you reach the step to select an agent, choose the **MSPortal** API-only agent you just created.

    <Card title="Configure Halo PSA Integration" icon="plug" href="/user-guides/integrations/enable-halo-integration">
      Complete guide to connecting Halo PSA with MSPortal.ai
    </Card>
  </Tab>
</Tabs>

## 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

<Card title="Configure Halo PSA Integration" icon="plug" href="/user-guides/integrations/enable-halo-integration">
  Complete guide to connecting Halo PSA with MSPortal.ai
</Card>