Connect Cisco Duo

Cisco Duo is a multi-factor authentication and identity-security platform. StackJack connects to it through Duo's two published APIs — the Admin API, which manages your Duo directory, and the Auth API, which performs authentications — covering users, phones, hardware tokens, passkeys, desktop authenticators, groups, policies, protected applications, administrators, authentication logs, Trust Monitor, custom branding, and MSP subaccounts.

Connecting Duo to StackJack gives your AI assistant a broad family of duo_ MCP tools — MCP (Model Context Protocol) tools are the standardized commands an AI assistant can call through StackJack. With them, your AI can:

• Audit your directory — users and their enrolled devices, groups, bypass codes, passkeys, desktop authenticators, and endpoints
• Investigate authentications — read authentication, activity, telephony, administrator and offline-enrollment logs, plus Trust Monitor events
• Review policy and posture — list policies, retrieve any policy or the global policy, and calculate the effective policy that actually applies
• Report on the account — utilization summaries, telephony credits used, and authentication-attempt reports
• Manage the directory (on Pro plans) — create and modify users, phones, tokens, groups, administrators and administrative units; associate and disassociate devices; block and unblock registered devices
• Manage configuration (on Pro plans) — protected applications, policies, global settings, Passport, and the draft/live custom-branding workflow
• Run authentications (on Pro plans, with the Auth API configured) — pre-authenticate a user, send a Duo Push or place a phone callback, validate a passcode, and enroll a new user
• Administer subaccounts (on Pro plans) — list, create and delete MSP subaccounts and set their edition and telephony credits

How StackJack authenticates to Cisco Duo

Duo does not issue access tokens. Instead, every request is signed individually: StackJack computes a signature from the request itself using your secret key, and Duo verifies it. There is nothing to expire, nothing to refresh, and no consent screen — but it does mean two things matter.

Duo's Admin API and Auth API are two separate applications. Each is created independently in the Duo Admin Panel and each has its own integration key and secret key. They are not interchangeable: entering one application's keys in the other's fields is the most common setup mistake, and Duo reports it as a permission error rather than an invalid-key error. StackJack accepts either or both:

• The Admin API pair powers everything that reads or manages your Duo directory, policies, applications, logs and reports. Add this one first.
• The Auth API pair is optional and powers the authentication family (pre-authentication, push, passcode, phone callback, enrollment and status polling). Add it only if you want your AI to run authentications.

The API hostname is specific to your account. It looks like api-abc12345.duosecurity.com. Copy it exactly as it appears in the Duo Admin Panel — it is not a region you choose, and it cannot be worked out from an integration key.

Because each request is signed with a timestamp, Duo rejects requests whose clock is far from its own. StackJack handles this for you, but a badly wrong server clock is worth ruling out if every Duo tool suddenly fails to authenticate at once.

Permissions are set per application

Duo application permissions are independent of your own administrator role. A correctly signed request can still be refused because the application it came from was never granted that permission. When you create the Admin API application you tick the permissions it may use — reads and writes for resources such as users, phones and policies; log reading; settings; administrator management; identity verification; and the subaccount permissions if you are an MSP. Grant only what the tools you intend to use require.

Duo also validates the signature before applying any source-IP restriction you have configured. That ordering is useful to know: a request that is correctly signed but refused because it came from an unknown IP address can be a sign that your secret key has leaked.

Before you begin

• In StackJack: you need a role that can manage connectors (tenant Owner, a co-owner, or an Administrator).
• In Duo: you need an administrator with the Owner role — only an Owner can create or modify an Admin API application.
• Plan requirements: the Admin API is included with Duo Essentials, Advantage and Premier, and with new Advantage or Premier trials. The Auth API is additionally available to Duo Free and trial accounts. Some individual endpoints still require a specific edition.

Step 1 — Create an Admin API application in Duo

1. Sign in to the Duo Admin Panel as an administrator with the Owner role.
2. Go to Applications → Application Catalog.
3. Locate Admin API and click + Add.

Step 2 — Grant the permissions you need

On the new application's page, tick the permissions matching the tools you plan to use — for example resource read and write for users, phones and policies; log reading for the authentication and activity logs; settings for global settings and branding; and the administrator permissions for managing administrators and administrative units. MSPs administering subaccounts also need the accounts and user-limit permissions.

You can widen these later, but a missing permission shows up as a refused tool call rather than a setup error, so it is worth getting right now.

Step 3 — Copy the hostname and key pair

From the application's details, copy:

• the API hostname (for example api-abc12345.duosecurity.com),
• the integration key, and
• the secret key.

Treat the secret key like a password.

Step 4 (optional) — Create an Auth API application

Only needed if you want the authentication tools. Return to Applications → Application Catalog, locate Auth API with the 2FA label, click + Add, and copy that application's own integration key and secret key. It is a different application with a different key pair. Before testing, grant the users who will authenticate access to the new application; new applications do not allow active users until you set User access for selected groups or all users.

Step 5 — Add the credentials in StackJack

1. In the StackJack portal, open Connectors.
2. Find the Cisco Duo card. Click How To Connect for the same steps inline, or Configure to enter the credentials.
3. Paste the API Hostname.
4. Paste the Admin API Integration Key and Admin API Secret Key.
5. If you created an Auth API application, paste its Auth API Integration Key and Auth API Secret Key in the optional fields.
6. Click Save.

What happens when you save

• Both key pairs are stored encrypted in Azure Key Vault — never in the StackJack database, and never shown back to you.
• If this is the first time you configure Duo, a Free-tier subscription for the connector is created automatically so its Free tools work right away.
• StackJack immediately live-validates the credentials with a small account read. Validation never blocks the save: you'll either see a success confirmation or a "saved but validation failed" warning with the reason.
• Because Duo checks the signature before checking permissions, a validation result of "permission denied" still confirms your keys are correct — it only means the application has not been granted that particular read. StackJack treats that as valid.
• The connector card shows the connection and validity status from then on.

When you later update the connector, leaving a secret field blank keeps the stored value, so you can change the hostname or one pair without re-entering the other.

How Duo returns results

Duo wraps every response in a status envelope, and StackJack passes it through unchanged. Two things follow from that:

• A request can succeed at the HTTP level and still report a failure. Duo returns a status of FAIL together with a code and message when it rejects a request — a bad parameter, a policy denial, an expired code. Your AI reads that and can adjust; it is not a StackJack outage.
• Paging differs between the logs and everything else. Ordinary lists page by a numeric offset. The authentication, activity and telephony logs instead return a cursor that must be passed back exactly as received, and they take their time ranges in milliseconds. Your AI handles this, but it is why a log query looks different from a user query.

Authentication log results have an intentional two-minute delay before new events appear, and Duo recommends requesting logs no more than once a minute. A query for the last few seconds legitimately comes back empty.

Plans and available tools

• Free includes list and get operations across users, devices, groups, policies, applications, administrators, endpoints, Trust Monitor, logs, settings, branding and account reports, plus enrollment- and authentication-status polling.
• Pro adds create, modify and delete operations across the directory; policy, settings, application and branding changes; device block/unblock; subaccount and billing management; and authentication actions.
• Business offers the same tool set as Pro with a higher monthly call quota.

See the generated Cisco Duo tool reference for the current inventory, plan assignment, input schemas, and destructive-action labels.

Duo issues account-scoped integration keys rather than per-user logins, so there is no per-user attribution — all AI traffic authenticates as the application. Current pricing and quotas are shown in the portal's Billing page and at checkout.

Safety note — tools that reach real people. Some Pro tools do more than change a record. Sending a Duo Push, placing a phone callback, or texting passcodes, activation codes or installation links contacts a real person's device and spends telephony credits, and Duo provides no way to recall or de-duplicate one — a repeated authentication request is also how MFA-fatigue attacks work. Separately, deleting a user is immediate and permanent and does not use Duo's restorable Trash; resetting an application's client secret breaks every client using it; restricting administrator authentication factors can lock administrators out of the Duo Admin Panel; and a handful of read tools deliberately return existing secret material. Every one of these is flagged as requiring confirmation. Scope your AI's access deliberately — use the tool selections on the MCP Setup page and the Permissions page to enable only the actions you want an AI to take.

Rate limits

Duo does not publish a single account-wide request quota. It does publish a per-user authentication limit — 10 authentications per user per minute on Duo Free, and 30 per user per minute on Essentials, Advantage and Premier — and per-operation limits on its bulk user endpoints. StackJack paces tool calls per tenant and honors Duo's backoff responses, so a burst is slowed rather than sent all at once. Pacing is not a guarantee: retries are bounded, so a wide enough read can still come back throttled or time out. Narrow the read, honour any retry delay the vendor sends, and check whether a write landed before repeating it — see Retrying a failed or timed-out write.

The per-user authentication limit is worth knowing because it is per user, not per account: repeatedly authenticating one person can hit it while your overall traffic is low. StackJack never treats a rate-limit response as a successful authentication.

Rotating or replacing the credentials

The secret keys are the recovery secrets. If you regenerate a secret key in Duo, or delete and recreate an application, the stored credential stops working. To restore access, open Connectors → Cisco Duo → Configure in StackJack, paste the new key pair, and Save. You only need to re-enter the pair that changed — leaving the other blank keeps it.

Several customers

Every customer has their own Duo account. Add one connection per customer from the connector's card, name it after the customer, and your AI names it on each call. Omit the name and the call runs against your default connection. Pin an endpoint to one connection when an AI should never reach past a single customer. See Several connections of one connector.

Troubleshooting

Cisco Duo tools

duo_ · 174 tools · Free 78 · Pro 96

Auth API

Users

User Associations

Phones

Hardware Tokens

WebAuthn Credentials

Desktop Authenticators

Bypass Codes

Subaccounts

Groups

Identity Verification

Bulk Operations

Endpoints

Registered Devices

Trust Monitor

Integrations

Integrations (Legacy v2)

Policies

Passport

Administrators

Admin Access

Admin Roles

Administrative Units

Logs

Settings

Custom Branding

Account Reports