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

# Duo Admin

> Connect Duo Admin API to import MFA authentication events and user data.

export const ConnectInPlatform = ({tile, children}) => <Step title="Enter the credentials in the Living Security Platform">
    <p>
      Completed by whoever holds Living Security access — the program owner, or the system
      admin if they've been invited (delegated setup).
    </p>
    <ol>
      <li>
        Go to <strong>Settings → Integrations → Catalog</strong>, find the{' '}
        <strong>{tile}</strong> tile, click <strong>Connect</strong>.
      </li>
      <li>
        Fill in the fields below, then click <strong>Connect</strong>.
      </li>
    </ol>
    {children}
  </Step>;

export const SystemAdminBanner = ({system, recommendDelegated}) => <Note>
    <p>
      <strong>This guide is for your {system} administrator.</strong> It covers creating API
      credentials inside {system}, which requires admin access to {system} — not to the
      Living Security Platform.
    </p>
    <p>
      If you're the Living Security <strong>program owner</strong> and don't administer {system},
      send this page to whoever does. They complete Part A and hand the credentials back to you
      (or enter them directly if you've invited them into the platform).
      {recommendDelegated && <>
          {' '}Because setup produces sensitive key material, we recommend the{' '}
          <strong>delegated setup</strong> path so the secret is never sent back to you.
        </>}
    </p>
  </Note>;

<SystemAdminBanner system="Duo Security" recommendDelegated={true} />

## What Living Security needs

| Credential                 | Description                                                                                   |
| -------------------------- | --------------------------------------------------------------------------------------------- |
| **API hostname**           | The unique hostname for your Duo Admin API application (e.g., `api-XXXXXXXX.duosecurity.com`) |
| **Integration key (ikey)** | The client identifier for your Admin API application                                          |
| **Secret key (skey)**      | The HMAC-SHA1 signing key paired with the integration key                                     |

**Scopes:** Read log access + Read resource access

**Required role:** **Owner** (to create Admin API applications)

<Warning>
  The **secret key** is the HMAC-SHA1 signing key used to authenticate every API request — it is not a plain bearer token. Both the integration key and secret key are required.
</Warning>

### Prerequisites

* You must be signed in to the Duo Admin Panel with the **Owner** role. Only Owners can create or modify Admin API applications.

***

## Part A — In Duo Admin Panel

*Your Duo administrator completes these steps.*

<Steps>
  <Step title="Navigate to the Application Catalog">
    1. Sign in to your [Duo Admin Panel](https://admin.duosecurity.com).
    2. In the left navigation, click **Applications**, then select **Application Catalog**.
    3. Search for **Admin API**, then click **+ Add**.
  </Step>

  <Step title="Name your Admin API application">
    Give the application a descriptive name (e.g., `Living Security Platform`).
  </Step>

  <Step title="Grant the required permissions">
    Enable the following permission grants:

    | Permission                | Purpose                                              |
    | ------------------------- | ---------------------------------------------------- |
    | **Grant read log**        | Reads MFA authentication events (auth logs)          |
    | **Grant resource — Read** | Reads enrolled users, registered devices, and groups |

    <Note>
      Grant only these permissions. Do not enable Write permissions — they are not required.
    </Note>

    <Warning>
      If syncs return a `403` error after connecting, the application is missing a permission grant. Duo does not allow editing grants after creation — you must delete the application and create a new one with the correct grants.
    </Warning>
  </Step>

  <Step title="(Optional) Restrict network access">
    Under **Networks for API Access**, you may optionally enter IP addresses or CIDR ranges allowed to call this Admin API application.

    <Note>
      Contact your Living Security Customer Success Manager for current egress IP ranges if you want to restrict network access.
    </Note>
  </Step>

  <Step title="Save and copy your credentials">
    After saving, Duo displays:

    | Field               | Value                                                      |
    | ------------------- | ---------------------------------------------------------- |
    | **Integration key** | The client identifier (ikey)                               |
    | **Secret key**      | The HMAC-SHA1 signing key (skey)                           |
    | **API hostname**    | The unique hostname (e.g., `api-XXXXXXXX.duosecurity.com`) |

    Copy the API hostname exactly as shown — no `https://` prefix, no trailing slash.

    <Warning>
      Treat the **secret key like a password.** If lost, it cannot be retrieved — you must regenerate it or recreate the application.
    </Warning>
  </Step>
</Steps>

***

## Part B — In the Living Security Platform

*The program owner completes this step, or the system admin if using delegated setup.*

<Steps>
  <ConnectInPlatform tile="Duo Admin">
    | Field               | Value                                                                   |
    | ------------------- | ----------------------------------------------------------------------- |
    | **API key**         | The secret key (skey) from Part A, Step 5                               |
    | **API hostname**    | The hostname from Part A, Step 5 (e.g., `api-XXXXXXXX.duosecurity.com`) |
    | **Integration key** | The integration key (ikey) from Part A, Step 5                          |

    <Note>
      The **API key** field accepts the Duo **secret key (skey)**. This is intentional — Living Security uses the secret key as the HMAC-SHA1 signing credential on every request.
    </Note>

    <img src="https://mintcdn.com/livingsecurity/oVkrOMkYmNevekTI/integrations/images/duo-admin/connect-dialog.png?fit=max&auto=format&n=oVkrOMkYmNevekTI&q=85&s=2c0e8085715eee2de3bcc291c91aec2f" alt="Living Security connect dialog for Duo Admin" style={{maxWidth: "450px"}} width="576" height="486" data-path="integrations/images/duo-admin/connect-dialog.png" />
  </ConnectInPlatform>
</Steps>

You are now connected to Duo Admin.

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="401 Unauthorized">
    The secret key is invalid or the HMAC-SHA1 signature failed. Verify:

    1. The secret key was copied correctly (no extra spaces)
    2. The integration key matches the secret key from the same application
    3. The API hostname is correct
  </Accordion>

  <Accordion title="403 Forbidden">
    The application is missing one of the required permission grants (read log or read resource). Duo does not allow editing grants after creation — delete the application and create a new one with both grants enabled.
  </Accordion>

  <Accordion title="IP address blocked">
    If IP restrictions are configured on the Admin API application, verify Living Security's egress IP ranges are included. Contact support for current IP ranges.
  </Accordion>

  <Accordion title="API key vs Secret key confusion">
    The connection dialog's **API key** field expects the Duo **secret key (skey)**, not the integration key. The secret key is used for HMAC-SHA1 request signing.
  </Accordion>

  <Accordion title="Wrong API hostname format">
    Enter only the hostname (e.g., `api-XXXXXXXX.duosecurity.com`). Do not include `https://` or a trailing slash.
  </Accordion>
</AccordionGroup>