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

# Connecting ImmyBot to Neo

> Create a Microsoft Entra app, add it in ImmyBot as a user, save it in Neo and turn ImmyBot on per agent

You connect ImmyBot once at the MSP level, then turn it on per agent. Neo signs in to your ImmyBot instance as a Microsoft Entra app in your own Microsoft tenant, the way ImmyBot's own API guide sets up an outside integration.

## 1. Create an app registration in Microsoft Entra ID

**1. Register the app**

In the Microsoft Entra admin center of the tenant you sign in to ImmyBot with, open **App registrations** → **New registration**. Name it "Neo", keep the default settings, and click **Register**.

**2. Copy the ids**

On the app's **Overview** page, copy the **Application (client) ID** and the **Directory (tenant) ID**.

**3. Create a client secret**

Open **Certificates & secrets** → **New client secret**, add it, and copy its **Value**. Microsoft shows the value once; the **Secret ID** next to it is not the secret.

**4. Copy the Enterprise application's Object ID**

Back on the app's **Overview** page, click the **Managed application in local directory** link. It opens the app's Enterprise application. Copy the **Object ID** shown there.

> [!WARNING]
>
> ImmyBot needs the Object ID of the Enterprise application. The Object ID on the app registration's own Overview page is a different id, and ImmyBot will not know Neo's app if you paste that one.

## 2. Add the app in ImmyBot as a user

**1. Create a person**

In ImmyBot, go to **Show More** → **People** → **New**. Paste the Enterprise application's Object ID into **AD External ID** and save.

**2. Make the person a user**

Go back to the **People** list and click **Create User** on the person you just created.

**3. Give the user a role**

Open **Show More** → **Users**, edit the new user and give it a role. The role decides what Neo can do in ImmyBot, on top of the permission groups you set per agent. An admin role works for every group.

## 3. Add the app in Neo

**1. Open Integrations**

Open [**Integrations → ImmyBot**](https://dashboard.neoagent.io/integrations?tab=directory\&open=immybot) in the Neo Dashboard. The card is under Other.

**2. Save the credentials**

Fill in the four fields and click **Save**:

| Field | Value |
| - | - |
| **Instance URL** | The address you open ImmyBot at, for example `https://contoso.immy.bot` |
| **Tenant ID** | The **Directory (tenant) ID** from the app registration's Overview page |
| **Client ID** | The **Application (client) ID** from the same page |
| **Client Secret** | The secret's **Value** |

Neo gets a token from Microsoft with these values and calls ImmyBot with it before it saves. A wrong or expired secret, a wrong id, or an app ImmyBot does not know as a user is rejected straight away, with the step to fix.

**3. Check the Organization Mapping**

The **Organization Mapping** tab fills after the save, and again on each nightly PSA sync. Neo matches each ImmyBot tenant to a PSA company by the Azure tenant it is linked to, then by name. A name that two PSA companies share is left for you to map. See [ImmyBot](https://docs.neoagent.io/integrations/immybot/overview.md#your-clients-are-mapped-automatically) for how the matching works.

## 4. Turn ImmyBot on per agent

Open the agent from [**Agents**](https://dashboard.neoagent.io/agents), go to the Integrations section, and configure the ImmyBot block, under Other. Pick a profile, then change any group. Each group can be Disabled, Read Only or Read / Write.

| Group | What the agent can do |
| - | - |
| **Computers & Inventory** | Find a computer by name or user, read its installed software, inventory and online status, add a note, refresh its inventory, and move or exclude it from maintenance. |
| **Maintenance Sessions** | Start a maintenance session that installs, updates, repairs or removes one piece of software or runs one task on named computers; read each session's actions and logs; rerun, resume or cancel a session. |
| **Software & Task Library** | Look up software and tasks to deploy, and create or change them in your local library. Licence keys are hidden from Neo. |
| **Scripts** | Read and change scripts, and run a script on one computer or in a tenant's cloud context. A script runs any PowerShell its author wrote, so consider requiring technician approval here. |
| **Deployments & Schedules** | Read which deployments apply to a computer and why; create or change a deployment or a schedule, and run a schedule now. A deployment can apply to every computer of a tenant. |
| **Tenants & People** | Read and change tenants, people and tags, and sync people from Azure. |
| **Integrations & Agents** | Read each integration's health, clients and agents; install the ImmyBot agent on a computer through the RMM, sync clients and agents, and link clients to tenants. Integration credentials are hidden from Neo. |
| **Users, Roles & Settings** | Read users, roles, the audit log and notifications, and change preferences, branding and email settings. |

| Profile | What it does |
| - | - |
| **Read Only** | Reads every group, changes nothing |
| **Helpdesk** | Reads every group. Changes to computers and maintenance sessions, software installs included, ask a technician first |
| **IT Admin** | Installs, repairs and removes software, runs scripts and manages deployments on its own. Changes to integrations and to users, roles and settings ask a technician first |
| **Full Automation** | Every change with no approval, except those Safety Controls lists |

## Safety Controls

These always ask a technician, whatever the profile:

* Creating, changing or deleting ImmyBot users, roles, user groups and role assignments, granting a person access, turning on ImmyBot support access, and changing the Azure app credentials or pre-consenting client tenants in Azure, because each one grants access to the instance or to a client's tenant
* Impersonating an ImmyBot user
* Deleting or merging tenants, deleting computers in bulk, and deleting an integration
* Cancelling every maintenance session at once
* Restarting the instance, updating it, or changing its release channel
* Billing changes
* A write that sends a field named like a password, secret, key or token, such as a deployment parameter or an SMTP password, or that sends back a value Neo hid, which Neo fills from the stored record

In ImmyBot's JSON answers, Neo hides every field named like a credential: a password, a licence key, an integration's stored key or a deployment parameter named like one shows to the agent as `[hidden by Neo]`. Free text, such as a script's console output, is not inspected, so a script that prints a secret shows it to the agent.

Neo does not call these ImmyBot operations:

| Operation | Why |
| - | - |
| The console's browser sign-in and OAuth consent routes | They run the console's own session or a consent a person completes in a browser. Neo signs in with its own app. |
| The addresses where outside systems push webhooks and integration events | A call from Neo would feed the integration behind it an event that system never sent. |
| Creating ImmyBot agent installers: install scripts, installer and provisioning package links, and agent rekey requests | Each one enrols any machine that runs it into your instance. An agent with **Integrations & Agents** at Read / Write can install the ImmyBot agent on a computer your RMM already manages, through ImmyBot's RMM integration. A technician downloads an installer in ImmyBot. |
| Remote-control links | A link opens a session on the computer for whoever holds it. A technician starts remote control from the computer's page in ImmyBot. |
| Downloading the ImmyBot agent's binary | The answer is a file, which the agent cannot read. |
| A licence file's download link | The file holds the licence, which Neo hides like a licence key. A technician downloads it in ImmyBot. |
| Cancelling your ImmyBot subscription | It ends the instance for every client. The account owner does that in ImmyBot. |

See [ImmyBot API](https://docs.neoagent.io/agents/tools/rmm/immybot-api.md) for what the agent does with each group.


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