HaloITSM

Create an agent whose only purpose is API access for this integration, and assign it a read-only role. The OAuth application is bound to this agent, so the application's effective permissions are bounded by the agent's role.

1. Open Configuration. Go to the HaloITSM configuration / admin area.
2. Create or designate a read-only role. Under Teams & Agents → Roles (or the equivalent permissions area), create a role with read/view access to tickets, actions, and the reference objects listed above. Do not grant create, edit, delete, or administration permissions.
3. Create the integration agent. Under Agents, create an agent named CIOAnalytics with email cioanalytics@yourcompany.com, and assign the read-only role.
4. Save the agent. If your tenant does not allow object-level read scoping on a role, choose the narrowest available read-only role and note this for your Info-Tech onboarding contact.

HaloITSM agents default to seeing only their own tickets and no clients. The integration agent must be configured to see all tickets across all teams, all clients, and all ticket types. Without these settings, the API will return 200 OK but with zero or partial results - there is no error message indicating missing data.

Departments & Teams tab

1. Add the agent to all teams. Open the Departments & Teams tab and add the CIOAnalytics agent to every team (1st Line Support, 2nd Line Support, Facilities, Infrastructure, etc.). The membership level should be “Access to Teams Tickets” for each.

Permissions tab

2. Enable cross-agent ticket visibility. Under Tickets Permissions, set “Can view Tickets that are assigned to other Agents” to Yes. Without this, the API returns only tickets assigned to the CIOAnalytics agent itself - which will be none.
3. Enable all ticket types. Under Ticket Type Restrictions, set “Allow use of all Ticket Types” to Yes. If this is left as “Not set” with an empty Accessible Ticket Types list, the agent may be silently filtered to a subset of ticket types.

Client Restrictions tab

4. Enable all clients. Set “Allow use of all Clients” to Yes so the agent can see tickets from every client organization. Do not enable the Co-managed IT Agent toggle or set a Client Group Override - the Co-managed flag restricts the agent's visibility model and is not appropriate for an integration agent.

Halo's REST API is OAuth2-protected. Register an API application to obtain a client ID and client secret the integration uses to request access tokens from your tenant's OAuth2 token endpoint.

1. Open the Halo API integration area. Under Configuration → Integrations, open the Halo API / API Applications section.
2. Create a new API application. Name it Info-Tech CIOAnalytics.
3. Choose the authentication method. Select the Client Credentials (server-to-server) flow if available, so the integration authenticates with the client ID and secret without an interactive login. If only an agent-bound flow is available, bind it to the CIOAnalytics agent from Step 1.
4. Record the credentials and endpoints. Save the Client ID and Client Secret, and note your tenant's authorization/token endpoint URL and API resource server URL (under /api). These go into the Info-Tech portal. Treat the client secret like a password.

Halo API applications are granted scopes that govern what the access token may do. The integration requires three specific read scopes. A token minted without any scope will return a valid access_token but produce 401 Unauthorized on all API endpoints.

Select these three scopes only

Note: /Agent and /Team are accessible with the above scopes - no additional scope is needed.

1. Grant the three read scopes. Assign read:tickets, read:customers, and read:timesheets to the API application. Do not select any edit:* scopes, admin, all, or all:teams.
2. Confirm the application is bound to the read-only agent from Step 1, so both the scope and the agent role constrain access.
3. Save the application.

Before entering the credentials in the Info-Tech portal, confirm the application can mint an access token and read tickets and the reference objects through the Halo REST API. Replace the host and endpoints with your tenant's values.

5.1 - Mint an access token

Request a token from your tenant's OAuth2 token endpoint using the client credentials. The scope parameter is required - omitting it produces a token with no API access.

curl --ssl-no-revoke -X POST "https://YOUR_TENANT/auth/token" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=YOUR_CLIENT_ID" \
  --data-urlencode "client_secret=YOUR_CLIENT_SECRET" \
  --data-urlencode "scope=read:tickets read:customers read:timesheets"

You should receive a JSON response containing an access_token. The exact token endpoint path varies by tenant - confirm it in your Halo API configuration. If the request fails, recheck the client ID, secret, scope, and endpoint.

5.2 - Test a basic ticket read

Using the access token:

curl --ssl-no-revoke -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  "https://YOUR_TENANT/api/Tickets?count=1"

A successful response returns ticket JSON with record_count greater than zero. If record_count is 0 but you know tickets exist, review the agent permissions in Step 2 - particularly “Can view Tickets that are assigned to other Agents” and “Allow use of all Clients”. 401 Unauthorized means the token has no API access - recheck that the scope parameter was included in the token request. 403 Forbidden means the application or agent lacks read access for that endpoint.

5.3 - Test the time-entries (worklog) read

Confirm the filtered Actions endpoint returns time entries:

curl --ssl-no-revoke -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  "https://YOUR_TENANT/api/Actions?timeentriesonly=true&count=1"

Confirm the response includes timing fields such as timetaken. If the endpoint or filter is not recognized, flag it with your Info-Tech onboarding contact.

5.4 - Test reference reads

Confirm each returns data. If any return 403 Forbidden, add the minimum read scope/role permission for that object and test again:

/api/Users?count=1
/api/Agent?count=1
/api/Team?count=1
/api/Client?count=1
/api/Site?count=1
/api/Status?count=1
/api/Priority?count=1
/api/Category?count=1
/api/TicketType?count=1
/api/SLA?count=1

5.5 - Verify complete data retrieval

As a final check, confirm the total ticket count from the API matches what the HaloITSM UI shows. Fetch all tickets (use a high count value) and compare record_count to the total across all views in the UI:

curl --ssl-no-revoke -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  "https://YOUR_TENANT/api/Tickets?count=1000"

If the API count is significantly lower than the UI total, review Step 2 - the agent may be missing team membership, client visibility, or ticket type access.

1. Go to https://us.app.cioanalytics.ai/
2. Open the Connections page.
3. On the IT Service Management (ITSM) row, click Connect Tool.
4.  In the Connect to ITSM Tool dialog, select  HaloITSM  from the dropdown.
5. Click Continue.
6. Follow the instructions in the Setup Guide panel on the right to fill in the fields on the left.
7. When every field is complete, click Add Connection.
8. Wait for the connection test to finish.

After the connection test succeeds, CIO Analytics takes over the rest of the process automatically.

1. You are returned to the Connections page once the connection is saved.
2. Your HaloITSM data syncs automatically for the first time. Depending on how much history is being pulled, the first sync can take anywhere from a few hours to a few days.
3. Once that first sync completes, an Info-Tech analyst will reach out to you to continue your onboarding. No further action is needed from you in the meantime.