> ## 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 Duo to Neo

> Create a Duo Admin API application and save its integration key, secret key and API hostname in Neo

Neo connects to Duo through an Admin API application. Duo includes the Admin API in the Duo Essentials, Advantage and Premier plans, and only a Duo administrator with the **Owner** role can create the application.

## 1. Create an Admin API application for Neo

<Steps>
  <Step title="Add the application">
    Log in to the Duo Admin Panel and open **Applications** > **Application Catalog**. Find **Admin API** and click **+ Add**.

    With a Duo MSP account, do this in your own (parent) account. One application there reaches every client subaccount, so you do not create one in each subaccount.
  </Step>

  <Step title="Copy the keys and the hostname">
    On the application's page, copy the **Integration key**, the **Secret key** and the **API hostname** (for example `api-1a2b3c4d.duosecurity.com`). Treat the secret key like a password.
  </Step>

  <Step title="Tick the permissions">
    Tick the permissions for what you want Neo to do. The first three cover the lockout and onboarding work:

    | Duo permission | What it lets Neo do |
    | - | - |
    | **Grant resource - Read** and **Grant resource - Write** | Users, phones, tokens, bypass codes, groups, devices and policies, and the verification Duo Push |
    | **Grant read log** | Authentication, administrator and telephony logs, to see why a user was denied or locked out |
    | **Grant read information** | The account summary and usage |
    | **Grant identity verification - Read** and **- Write** | Duo identity verification of a user |
    | **Grant administrators - Read** or **- Write** | Duo administrators, roles and administrative units |
    | **Grant applications** | The applications Duo protects |
    | **Grant settings** | Global account settings and branding |

    Tick **Grant set Admin API permissions** only if you want Neo to grant Admin API permissions to another Duo application. Neo asks a technician before every such grant. Leave it unticked otherwise.
  </Step>

  <Step title="As an MSP, tick the subaccount permissions">
    Under **Subaccount permissions**, tick **Grant accounts - Read**, so Neo can list your client subaccounts, and the same permissions you ticked above. Without them, Neo sees only your own account and none of your clients.

    Tick **Grant accounts - Write** only if you want Neo to create subaccounts and set a subaccount's edition and telephony credits, and **Grant user limits - Read** and **- Write** for a subaccount's user limit.
  </Step>

  <Step title="Optionally restrict the networks">
    **Networks for API Access** limits where the application can be used from. Leave it empty to allow any network, or add [Neo's IP addresses](/integrations/ip-whitelisting). If you restrict it and leave out one of Neo's addresses, Duo refuses some of Neo's requests.
  </Step>

  <Step title="Save the application">
    Scroll to the bottom of the page and click **Save**.
  </Step>
</Steps>

## 2. Add the keys in Neo

<Steps>
  <Step title="Open Integrations">
    In the Neo Dashboard, open [**Integrations** → **Duo**](https://dashboard.neoagent.io/integrations?open=duo), under Security.
  </Step>

  <Step title="Save the keys and the hostname">
    Paste the API hostname, the integration key and the secret key, and click **Save settings**. Neo signs a request to Duo with them before saving, so a mistyped key or hostname is rejected straight away. The check reads one user, so it also rejects keys of another application type and an Admin API application without **Grant resource - Read**. Any other missing permission is not caught here: Duo refuses that call later, when an agent makes it.
  </Step>
</Steps>

## 3. Turn Duo on per agent

<Steps>
  <Step title="Open the agent">
    In the Neo Dashboard, open the agent and its **Integrations** tab.
  </Step>

  <Step title="Choose an access profile">
    Under **Duo**, choose a profile, or set each permission group by hand.
  </Step>

  <Step title="Tell the agent what to do">
    Add a line to the agent's instructions, for example: "When a user is locked out of Duo, verify the caller with a Duo Push, then set the user active again and note what you did on the ticket."
  </Step>
</Steps>

| Profile | Runs on its own | Asks a technician |
| - | - | - |
| **Read Only** | Every read | No write is allowed |
| **Helpdesk** | Every read, and the verification Duo Push | Changes to users, phones, bypass codes and groups. Other areas are read only |
| **IT Admin** | Changes to users, phones and groups, and the verification Duo Push | Changes to bypass codes, devices, applications and subaccounts, plus the changes that always ask |
| **Full Automation** | Every change except the ones below that always ask | The changes that always ask |

Under every profile, a technician approves setting a user or group to bypass, adding a user to a group, creating bypass codes, deleting a phone, hardware token, security key or desktop authenticator, detaching a phone or token from a user, every policy, account setting and administrator change, creating or deleting an application, resetting its secret key or granting it Admin API permissions, and changing a subaccount's edition, telephony credits or user limit. The [Duo API](/agents/tools/security/duo-api) page lists the permission groups and what Neo never sends.

## Client subaccounts

Neo finds each client's subaccount by its account id and sends the call to that subaccount's own API hostname. Each subaccount is mapped to a client in your PSA on the Duo card's **Organization Mapping** tab; see [Duo overview](/integrations/duo/overview#your-subaccounts-are-mapped-to-clients). With **Grant accounts - Read** ticked, an agent on a ticket reaches only the subaccount mapped to the ticket's client, and never your own account when the client has no mapped subaccount, so map every client you want agents to work on. Without it, Neo may not know your subaccounts, and a ticket call without an account id can then reach your own account.


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