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

# Duo

## After this article

You will be able to connect Duo (Cisco Duo) to Lumos to sync users, admins, groups, roles, and last login timestamps for Access Reviews and license management. You can also create, activate, deactivate, and delete accounts and manage group and role assignments from Lumos.

## Capabilities

| Functionality | Type | Sync | Provision | Description |
| - | - | - | - | - |
| Users | Account | Yes | Yes | Duo users and Duo administrators. Lumos can create, activate, deactivate, and delete both |
| Groups | Permission | Yes | Yes | Duo groups. Lumos can assign and unassign them, for regular users only |
| Roles | Permission | Yes | Yes | Duo admin roles. Lumos can assign them, for administrator accounts only |

**Activity tracking is supported:** the integration syncs each user's last login timestamp.

**Provisioning behavior:**

* **Create:** requires a username, an email, and an account type (user or admin). For users, Lumos checks the username first and links an existing user instead of creating a duplicate. For admins, Duo has no lookup by name or email, so Lumos relies on Duo's duplicate-email error to link an existing admin. Passwords aren't supported: Duo's user creation endpoint has no password field, and its admin creation endpoint ignores the deprecated password field.
* **Assign or remove a group:** regular users only. Assigning a group the user already has, or removing one they don't, is a safe no-op.
* **Assign a role:** administrator accounts only. An admin has exactly one role, so assigning a new role replaces the current one. Assigning the role the admin already has is a safe no-op.
* **Remove a role:** not supported. Duo requires every admin to hold a role. Assign a different role instead.
* **Activate and deactivate:** Lumos sets the account's status in Duo (works for users and admins), and skips the call if the account is already in the target state. Admins with the **Owner** role can't be deactivated, assign a different role first. Admins in a pending state (for example awaiting email verification) can't be activated through the API.
* **Delete:** Lumos resolves whether the ID is a user or an admin first. If the account is already gone, the delete is a safe no-op.

## Required plan and roles

* **Duo role:** you need access to the **Duo Admin Panel** to create an Admin API application (this is done under **Applications → Protect an Application**).
* **Permission scoping:** Duo Admin API applications carry permission grants. Syncing needs the **Grant resource - Read** and **Grant administrators - Read** permissions. Provisioning also needs **Grant resource - Write** (users and groups) and **Grant administrators - Write** (admins and roles). Connecting in read-only means not providing the write permission grants.
* **Sync vs provisioning:** both run over the same Duo Admin API with the same Integration Key and Secret Key.

## Instructions

**Phase 1: Create an Admin API application in Duo**

1. Log in to the **Duo Admin Panel**.
2. Go to **Applications → Protect an Application**.
3. Locate **Admin API** in the applications list and click **Protect** on the far right.
4. From the application configuration page, copy the **Integration Key** and **Secret Key**.
5. Note the **API hostname**. The **Subdomain** is its first segment (for `https://api-333bbc60.duosecurity.com`, the subdomain is `api-333bbc60`).

**Phase 2: Connect in Lumos**

1. Find the Duo card in your Lumos integrations (reconnect an existing card or add a new one).
2. Enter the **Secret Key**, **Integration Key**, and **Subdomain**.
3. Click **Connect**.

## API Endpoints Used

<Note>
  The API endpoints this integration uses are available to logged-in Lumos customers. [Log in](/login) to view them.
</Note>

## Troubleshooting

**Connection fails with valid keys.** Check the **Subdomain** value: it must be only the first segment of the API hostname (e.g. `api-333bbc60`), not the full URL. Confirm the keys came from an **Admin API** application, not another Duo application type.

**Provisioning actions are unavailable or fail.** Check the Admin API application's permission grants in Duo: user and group changes need **Grant resource - Write**, and admin and role changes need **Grant administrators - Write**. Older Duo connections (before June 2026) are read-only, so reconnect or contact Lumos support to enable provisioning for them.

**Deactivating an admin fails.** Admins holding the **Owner** role can't be deactivated through the API. Assign a different role first, then deactivate.