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

# HaloITSM

> Connect HaloITSM to Oleria to discover agents, end users, API applications, roles, teams, and departments, and take remediation actions in your Halo tenant.

HaloITSM is an IT service management platform from Halo Service Solutions. Connect your Halo tenant to Oleria to see who can sign in to it and how: every agent and end user, the roles, teams, and departments they belong to, and the API applications that act on the tenant. Oleria reads this data from the Halo API with the client credentials of a Halo API application. You can review access to your service desk and take action directly from Oleria.

## What Oleria discovers

Once connected, Oleria continuously discovers and maps the following from your Halo tenant:

* **Accounts** - every agent, including disabled and API-only agents, and every end user, including inactive end users. Halo's per-site general user isn't imported. Each account shows the name, email address, whether it's enabled, its last login, and its two-factor authentication and single sign-on (SSO) status. Agents also show their job title, line manager, and creation date. An end user linked to an agent appears once, as the agent.
* **Administrators** - agents with the **Is an Administrator** permission are marked as administrators.
* **Non-human identities** - API applications, shown with the agent each one logs in as and the scopes it's granted. API-only agents (**Is an API-only Agent**, or **Agent Access** set to **API Only**) and end users marked as service accounts are also imported as machine accounts. Agents with **Agent Access** set to **Dashboard Only** are imported as people. Halo's system applications are marked as system accounts.
* **Credentials** - the client secret, API key, or JWT assertion key of each API application, and any federated credentials it trusts. Oleria imports only metadata, such as the type and whether the application is active. It never reads secret values.
* **Groups** - teams and agent departments, with their members and the agents who manage them. Memberships that an agent gets from a role are included. Each team is shown inside its department, and each department inside its parent department.
* **Roles** - agent roles and end-user roles, with the agents and end users who hold them.

Oleria refreshes this data on its [regular sync schedule](/integrations/overview.md#sync-model).

> [!NOTE]
>
> Oleria doesn't import tickets, assets, clients, sites, contracts, or other service desk content. Halo has no identity audit or sign-in API, so Oleria doesn't import activity. See [Known limitations](#known-limitations).

## Prerequisites

* A HaloITSM tenant, hosted by Halo or on-premise, that Oleria can reach over HTTPS from the internet.
* A Halo administrator who can create agents and API applications.
* For a custom domain or an on-premise Halo host, an allowlist entry for that host. Contact [support@oleria.com](mailto:support@oleria.com) before you connect. Hosts under `haloitsm.com` and `haloservicedesk.com` don't need one.
* Admin access to the Oleria workspace.

## Create the Halo API application

**1. Create an integration agent**

In Halo, go to **Configuration** > **Teams & Agents** > **Agents** and create a dedicated agent for Oleria. Under **Permissions**, give it the **Is an Administrator** permission. We recommend making it API-only (**Agent Access** set to **API Only**, or **Is an API-only Agent** on older Halo versions): an API-only agent takes no Halo license and can't sign in to the Halo web or mobile apps.

The agent must be an administrator. Halo shows non-administrators only the agents and teams they can edit, so Oleria refuses a non-administrator agent rather than sync a partial inventory. Oleria also runs [remediation actions](#remediation-actions) as this agent.

**2. Create the API application**

Go to **Configuration** > **Integrations** > **Halo API** > **View Applications**, select **New**, name the application, and make sure it's enabled. Set it up as follows:

| Setting | Value |
| :- | :- |
| Authentication method | **Client ID and Secret (Services)** |
| Login type | **Agent** |
| Agent to log in as | The integration agent you created |

**3. Grant the all scope**

In the application's permissions, select the `all` scope. Oleria requests this scope when it signs in. Halo has no read-only administrator scope.

Halo also limits the application to what its log-in agent is allowed to do, so the agent's permissions decide what Oleria can read and change.

**4. Copy the client credentials**

Save the application, then copy its **Client ID** and **Client Secret**. You'll paste them into Oleria in the next section.

> [!NOTE]
>
> Store the client secret securely, and rotate it per your organization's security policy.

> [!NOTE]
>
> The exact location of these settings can change between Halo versions. If the steps above don't match what you see, refer to Halo's guide to creating API applications.

The integration needs these Halo permissions:

| Oleria needs to | Halo permission |
| :- | :- |
| Sign in | An active API application that uses **Client ID and Secret (Services)**, with the `all` scope |
| Read agents, teams, departments, roles, API applications, and tenant security settings | A log-in agent with **Is an Administrator** |
| Read end users | The log-in agent's **Customers Read** permission. The `all` scope already includes the matching application scope, `read:customers`. |
| Run remediation actions | A log-in agent with **Is an Administrator**. Actions on end users also need the log-in agent's **Customers Modify** permission (application scope `edit:customers`, included in `all`). |

If the log-in agent can't read end users, API applications, roles, departments, or tenant security settings, Oleria skips them and syncs the rest. If it can list API applications but can't open them, Oleria still syncs those applications but without their scopes and federated credentials, and logs the missing permission. If it can't read agents or teams, the sync fails.

## Connect HaloITSM to Oleria

**1. Open the integration**

Go to your Oleria workspace, select **Integrations**, then select the **HaloITSM** tile.

**2. Complete the connection form**

Fill in the connection form:

| Field | Notes |
| :- | :- |
| Halo URL | Required. The https address of your Halo web application, for example `https://yourcompany.haloitsm.com`, or your custom or on-premise Halo host. The Halo API is served from the same address. Oleria adds `https://` if you leave it out and removes a trailing `/api` or `/auth`. IP addresses and addresses with credentials, a query, or a fragment aren't accepted. |
| Client ID | Required. The Client ID of your Halo API application. |
| Client secret | Required. The Client Secret of the same API application. |
| Tenant | Optional, hosted Halo only. Your Halo tenant name. Oleria normally finds your tenant from your Halo URL, so enter it only if **Authenticate** can't find your tenant. Leave it blank for on-premise Halo. |

**3. Confirm the connection**

Select **Authenticate**. Oleria signs in with the client credentials, checks that the log-in agent is an administrator, reads one agent and one team, and identifies your Halo tenant before saving the integration.

> [!NOTE]
>
> You can connect each Halo tenant to Oleria once. To connect a different tenant, add a new integration.

## Verify the integration

Confirm the HaloITSM instance appears on the **Connected** tab of your Oleria **Integrations** page with a status of **Healthy**. The integration's **Capabilities** tab shows **Read users**, **Read groups**, and **Read roles** with the Halo permissions each one needs, and checks them against your API application. After the first sync completes, you can review the discovered accounts, non-human identities, groups, and roles in your Oleria workspace.

## Edit the integration

You can change the **Client ID**, **Client secret**, and **Tenant** of an existing integration, for example to rotate the client secret. Select **Update** to validate and save your changes.

* To keep the stored client secret, leave **Client secret** empty.
* To remove a stored tenant name, clear **Tenant**.
* You can't change the **Halo URL** of an existing integration. To connect another Halo URL, add a new integration.
* The new credentials must belong to the same Halo tenant. Oleria refuses credentials from a different tenant.

## Remediation actions

Oleria can take these actions in Halo. Each one runs as the API application's log-in agent, and Oleria checks that the agent is still an administrator before it runs.

| Action | Applies to | What it does | Revert |
| :- | :- | :- | :- |
| Disable user | Agents and end users | Disables the agent, or marks the end user inactive. | Supported - enables the account again. |
| Enable user | Agents and end users | Enables the agent, or marks the end user active. | Supported - disables the account again. |
| Add user to role | Agents and end users | Adds an agent role to an agent, or an end-user role to an end user. | Supported - removes the role. |
| Remove user from role | Agents and end users | Removes the role. Other roles are kept. | Supported - adds the role back. |
| Add user to group | Agents | Adds the agent to a team or department. | Supported - removes the agent from it. |
| Remove user from group | Agents | Removes the agent from a team or department. Other memberships are kept. | Supported - adds the agent back with the membership's previous settings. |
| Create user | Agents | Creates an agent with the name, email address, and teams or departments you give. The agent is disabled unless you choose to activate it. | Supported - disables the agent Oleria created. |
| Delete user | Agents | Deletes the agent from Halo. | Not supported. |
| Create group | Teams | Creates a team with the name you give. | Supported - deletes the team, only if Oleria created it and it has no members. |
| Revoke user sessions | Agents | Sends Halo's revoke-tokens request for the agent. In Halo, revoking an agent's tokens makes the agent sign in again, including any two-factor or SSO steps. Oleria can't check the agent's sessions afterwards, so check Halo if you need to be sure. | Not supported. |
| Disable NHI | API applications, API-only agents, and end-user service accounts | Marks the API application or service account inactive, or disables the API-only agent. | Supported - enables it again. |

> [!WARNING]
>
> **Delete user** and **Revoke user sessions** can't be undone. Halo can't restore a deleted agent through its API. Before you delete an agent, consider disabling it instead.

Keep these limits in mind when you use these actions:

* Oleria reads the account, role, group, or application before it changes it. If it's already in the requested state, the action makes no change, and reverting it makes no change either.
* Oleria sends each change once, then reads it again to confirm. If Halo's response is lost and the change doesn't show when Oleria reads it again, the action fails and reports that the change may have been applied. Check Halo before you run the action again.
* Oleria refuses to disable, delete, revoke the sessions of, or change the roles or groups of the integration's own log-in agent, and refuses to disable the integration's own API application. These changes would disconnect the integration.
* Oleria refuses to disable Halo's system applications, to remove an agent's last role, and to add a role or group that doesn't exist in Halo. To remove an agent's last role, assign another role first or disable the agent.
* Agents hold agent roles, and end users hold end-user roles. Team and department actions, **Delete user**, and **Revoke user sessions** apply to agents only. Oleria can't delete end users.
* If an agent's team or department membership comes from one of their roles, **Remove user from group** refuses it. Remove the role instead.
* If you sync users into Halo from Microsoft Entra ID (Azure AD) or Okta, the next sync may overwrite role changes made from Oleria.
* **Create user** doesn't set a password. The new agent signs in with SSO or Halo's password reset. If an agent with the same email address already exists, the action makes no change. Reverting **Create user** disables the agent instead of deleting it.
* **Create group** makes no change if a team with the same name already exists.
* **Disable NHI** applies only to API applications, API-only agents, and end users marked as service accounts. To disable another agent or end user, use **Disable user**. Tokens an API application already holds may keep working until they expire, which is up to an hour.
* Halo doesn't expose session state, so Oleria confirms **Revoke user sessions** only from Halo's response.

## Known limitations

* **No activity.** Halo has no identity audit or sign-in API, so Oleria doesn't import activity. Each account's last login is still shown.
* **No last password change.** Halo doesn't report when an agent or end user last changed their password.
* **Team and department nesting shows Halo's structure.** Oleria shows each team inside its department, as Halo organizes them. Halo doesn't document whether a department's access extends to the members of its teams, so confirm in Halo before you act on access that comes only through the nesting.
* **SSO is never shown as required.** Halo login stays available alongside SSO, so Oleria shows SSO as configured, not required. MFA shows as unavailable if the log-in agent can't read the tenant's security settings.
* **No API application owners or credential dates.** Halo's API doesn't report who created an API application, or when a credential was created, expires, or was last used.
* **Webhook, runbook, and connector secrets aren't imported.**
* **HaloPSA and HaloCRM.** HaloPSA and HaloCRM use the same API as HaloITSM, but Oleria offers only a HaloITSM tile. Their hosted domains, such as `halopsa.com` and `halocrm.io`, are treated as custom hosts and need an allowlist entry. Contact [support@oleria.com](mailto:support@oleria.com).
* **Custom and on-premise hosts.** Oleria connects to hosts under `haloitsm.com` and `haloservicedesk.com`. A custom domain or on-premise Halo host needs an allowlist entry for that exact host first. Contact [support@oleria.com](mailto:support@oleria.com). Hosts that resolve to private or loopback addresses can't be connected.
* **Rate limits.** Halo limits API requests per tenant, and your other Halo integrations share that limit. Oleria paces its requests to leave room for them, and during a sync it waits and retries when Halo reports the limit is reached. Actions aren't retried: if an action reports the rate limit, run it again later. A tenant with many end users takes longer to sync, about an hour for every 100,000 end users.
* **End-user roles on large tenants.** If Halo doesn't include end users' roles when it lists them, Oleria reads them one end user at a time, for up to 2,000 end users per sync. Role memberships of further end users aren't shown.

## Troubleshooting

| Message or symptom | What to do |
| :- | :- |
| The client ID or client secret was rejected | Check that the API application uses **Client ID and Secret (Services)**, then copy the Client ID and Client Secret from **Configuration** > **Integrations** > **Halo API** again. On a hosted tenant, if the credentials are correct, enter your tenant name in **Tenant**. |
| The API application's log-in agent is not an administrator | Set the application's **Agent to log in as** to an agent with **Is an Administrator** ticked. Oleria also shows this message when Halo refuses to list agents or teams. |
| The access token was refused (HTTP 401) | Check that the API application is active and that its permissions include the `all` scope. |
| Reading a record answered HTTP 404 | Check that the **Halo URL** is the address of your Halo web application. |
| Halo's API rate limit for this tenant is used up | Wait a few minutes, then try again. Other integrations that use the same Halo tenant share the limit. |
| The Halo sign-in settings (`/api/authinfo`) did not answer | Halo didn't respond in time. Try again in a few minutes. |
| The Halo URL must be an https address | Enter the `https://` address of your Halo web application, without a username, password, query, or fragment. IP addresses aren't accepted. |
| The Halo URL of an existing integration cannot be changed | Add a new integration for the other Halo URL. |
| These credentials belong to a different Halo tenant than this integration | Use credentials from the tenant this integration is connected to, or add a new integration for the other tenant. |
| The client secret must be the secret itself | Paste the client secret value from Halo. |
| **Authenticate** fails for a custom or on-premise host without a Halo error | Contact [support@oleria.com](mailto:support@oleria.com) to allowlist the host. |
| End users, API applications, roles, or departments are missing | The log-in agent can't read them, so Oleria skipped them. Check the agent's permissions in Halo. |
| An action reports it may have been applied | Check the account in Halo before you run the action again. |
| An action refuses to remove an agent's only role | Assign the agent another role first, or disable the agent. |
| An action refuses to remove an inherited membership | The membership comes from one of the agent's roles. Remove the role instead. |

## Contact us

For questions about this integration, contact us at [support@oleria.com](mailto:support@oleria.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.