Skip to main content

​
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

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.

​
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.
1

Sign in to the Duo Admin Panel

Only administrators with the Owner role can create or view Admin API applications.
2

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.
3

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.
4

Copy the credentials

Copy the integration key, secret key, and API hostname (e.g. api-xxxxxxxx.duosecurity.com) from the application page.
5

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.
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.

​
Connect in Serval

1

Open the Duo Security connect form

In Serval, add the Duo Security integration. It is labeled Beta.
2

API hostname

Paste your API hostname, e.g. api-xxxxxxxx.duosecurity.com (api-xxxxxxxx.duofederal.com for federal accounts).
3

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.
4

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.
5

Save and verify

Submit the form. Serval runs three health checks (below).
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.

​
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.
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.

​
Gotchas and troubleshooting

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.
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.
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.
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.
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.
Need help? Contact support@serval.com for assistance with your Duo Security integration.