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

# Duo Security

> Connect Serval to Cisco Duo so workflows can manage users, MFA devices, bypass codes, and logs through the Duo Admin API, and optionally send Duo Push prompts through the Auth API.

## About Duo Security

Cisco Duo is a multi-factor authentication and device-trust platform. The Serval Duo integration connects to your Duo account's **Admin API** application, giving workflows typed access to users, groups, phones, hardware tokens, WebAuthn credentials, bypass codes, administrators, logs, and account settings. Optionally, you can also attach an **Auth API** application to send Duo Push prompts and run pre-authentication checks from workflows. The integration is marked **Beta** in Serval's connect UI.

**Authentication:** Duo's signed-request scheme. Every API call is individually signed with HMAC using your application's integration key and secret key; there are no bearer tokens to rotate. Admin API and Auth API are separate Duo application types with separate key pairs, and Serval automatically signs each request with the right pair based on the endpoint.

**Data sync:** On demand only. There is no background user or group sync.

## What the Duo integration enables

| Capability            | Description                                                                                                                                                                                                                                                                                            |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Duo Admin API request | Typed requests across the Admin API: users (create, modify, delete, enroll), groups, phones and activations, hardware tokens, WebAuthn credentials, bypass codes, administrators, administrative units, authentication/administrator/telephony logs, Trust Monitor events, settings, and account info. |
| Duo Auth API request  | Optional: `/auth/v2` endpoints such as `preauth` (which factors a user can use) and `auth` (send a Duo Push and wait for the result). Requires Auth API credentials.                                                                                                                                   |
| Endpoint discovery    | Both API catalogs are indexed separately for workflow authoring, so the agent won't confuse Admin API and Auth API endpoints.                                                                                                                                                                          |

<Note>
  The Policies API, Passport API, and Integrations v2/v3 API are not available through this integration: Duo requires its newer v5 request signing for those endpoint groups, and this integration signs with v2. Everything else on the Admin API accepts v2-signed requests.
</Note>

## Get your credentials

You need your Duo **API hostname** and an **Admin API** application's integration key and secret key. Optionally, add an **Auth API** application's keys to enable `/auth/v2` workflows.

<Steps>
  <Step title="Sign in to the Duo Admin Panel">
    Only administrators with the **Owner** role can create or view Admin API applications.
  </Step>

  <Step title="Create the Admin API application">
    Go to **Applications → Protect an Application**, search for **Admin API**, and click **Protect**. If an Admin API application already exists, you can reuse it.
  </Step>

  <Step title="Choose permission grants">
    On the application page, grant only what your workflows need. **Grant resource - Read/Write** covers users, groups, phones, and bypass codes; **Grant read log** covers authentication and administrator logs; **Grant administrators** covers admin management.
  </Step>

  <Step title="Copy the credentials">
    Copy the **integration key**, **secret key**, and **API hostname** (e.g. `api-xxxxxxxx.duosecurity.com`) from the application page.
  </Step>

  <Step title="Optional: create an Auth API application">
    To send Duo Push prompts from workflows, also protect an **Auth API** application and copy its separate integration key and secret key. The API hostname is the same for all applications in your account.
  </Step>
</Steps>

<Warning>
  The Admin API secret key grants administrative access to your Duo account, limited only by the application's permission grants. Grant the minimum permissions your workflows need, and rotate the secret key in Duo if it is ever exposed.
</Warning>

## Connect in Serval

<Steps>
  <Step title="Open the Duo Security connect form">
    In Serval, add the Duo Security integration. It is labeled **Beta**.
  </Step>

  <Step title="API hostname">
    Paste your API hostname, e.g. `api-xxxxxxxx.duosecurity.com` (`api-xxxxxxxx.duofederal.com` for federal accounts).
  </Step>

  <Step title="Admin API integration key and secret key">
    Paste the Admin API application's integration key, and its secret key in the password field. Both must be provided together; needed for `/admin` and `/accounts` endpoints.
  </Step>

  <Step title="Auth API integration key and secret key">
    Paste the Auth API application's keys to enable `/auth/v2` endpoints. Both must be provided together; leave both blank to skip.
  </Step>

  <Step title="Save and verify">
    Submit the form. Serval runs three health checks (below).
  </Step>
</Steps>

<Note>
  Every field is optional at save time, so you can create the connection first and add credentials later; API calls and health checks report exactly which credentials are missing. When editing an existing connection, blank or obfuscated fields keep their stored values. Paste a new secret key to rotate credentials without re-entering everything else.
</Note>

## Verifying the connection

Three health checks run after you connect:

1. **Test Duo Admin API Connection** — fetches one user from `/admin/v1/users`. Confirms the hostname, integration key, and secret key are correct. Skipped (reported as healthy) when Admin API credentials are not configured.
2. **List Duo Groups** — fetches one group. Confirms resource read access. Skipped when Admin API credentials are not configured.
3. **Test Duo Auth API Connection** — calls `/auth/v2/check` with the Auth API credentials. Skipped when no Auth API credentials are configured.

<Tip>
  A 401 response usually means a wrong secret key or API hostname. A 403 means the request was signed correctly but the application lacks the permission grant for that endpoint — adjust the grants on the application page in the Duo Admin Panel.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Admin API and Auth API are different applications">
    The two APIs use separate credential pairs from separate Duo applications. Admin API keys cannot call `/auth/v2` endpoints and vice versa. Serval routes each request to the right pair automatically, but both must be configured in the connection for both APIs to work.
  </Accordion>

  <Accordion title="List parameters are comma-separated strings">
    Duo's request format only supports flat parameters. Where an endpoint accepts a list (e.g. bypass codes to create), pass a comma-separated string, not an array.
  </Accordion>

  <Accordion title="403 responses reflect missing permission grants">
    Each Admin API application carries explicit grants (resource read/write, log read, administrators, settings). An endpoint outside the granted set returns 403 even with valid keys.
  </Accordion>

  <Accordion title="Deleting users is a two-step trash flow">
    `DELETE /admin/v1/users/{user_id}` moves the user to the trash, where they remain restorable for 30 days before permanent deletion. Use the bulk restore endpoint to recover.
  </Accordion>

  <Accordion title="Rate limits">
    Duo returns 429 when an endpoint is called too frequently; bulk user creation is limited to 50 calls per minute. Serval retries with backoff, but long-running loops over large user sets should paginate with `limit`/`offset` rather than issuing per-user calls where a list endpoint exists.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Duo Security integration.