Duo Auth API
★ Only Publicly Available OpenAPI DocumentIdentity AuthAuthenticationbasic8 EndpointsREST
For Agents
Add Duo two-factor authentication to a workflow: pre-check users, send push or passcode prompts, and poll until the user approves or denies.
Use for: I need to send a Duo push to a user before they can continue, Check whether a user has Duo enrolled before prompting, Poll Duo to see if the user approved a push, Enroll a new user into Duo MFA
Not supported: Does not handle SSO, password storage, or directory sync — use for Duo two-factor authentication and enrollment only.
Jentic publishes the only available OpenAPI specification for Duo Auth API, keeping it validated and agent-ready. The Duo Auth API by Cisco Duo lets applications add second-factor authentication via push notification, passcode, phone callback, or SMS. The API exposes 8 endpoints covering server health checks, pre-authentication state, MFA enrollment, factor delivery, and authentication-status polling. Requests are signed using HMAC-SHA1, modelled in the spec as HTTP Basic with the integration key and the signature.
Install Jentic One Beta
Connect the Duo Auth API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Duo Auth API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Duo Auth API.
Verify the integration with Duo via GET /auth/v2/ping and GET /auth/v2/check
Pre-authenticate a user to discover available factors via POST /auth/v2/preauth
Send a push, passcode, phone, or SMS factor via POST /auth/v2/auth
Poll an asynchronous auth attempt via GET /auth/v2/auth_status
Enroll a new Duo user via POST /auth/v2/enroll
Check enrollment progress via POST /auth/v2/enroll_status
Fetch the configured branding logo via GET /auth/v2/logo
Use Cases
Patterns agents use Duo Auth API for, with concrete tasks.
★ Step-Up MFA for Sensitive Actions
Require a Duo push before a user runs a sensitive action like a wire transfer or admin password reset. The agent first calls POST /auth/v2/preauth to confirm the user is enrolled and discover their factors, then POST /auth/v2/auth with factor=push and async=1, then polls GET /auth/v2/auth_status until the user approves or denies. This adds a strong second factor without rewriting the primary login flow.
POST /auth/v2/preauth for the user, then POST /auth/v2/auth with factor='push' and async=1, then poll GET /auth/v2/auth_status until result is allow or deny
Self-Service Duo Enrollment
Enrol new employees or customers into Duo MFA from a self-service portal. POST /auth/v2/enroll creates an activation code and returns enrollment details, and POST /auth/v2/enroll_status lets the agent poll until the user has linked a device. This makes onboarding hands-off for IT, especially during large rollouts.
POST /auth/v2/enroll with username and email, deliver the activation_code to the user, then poll POST /auth/v2/enroll_status with the user_id until status is success
Health Monitoring for the Duo Integration
Run a scheduled health check that confirms an application's Duo integration is still valid before relying on it during an outage window. GET /auth/v2/ping returns the server status without auth, and GET /auth/v2/check verifies the integration credentials. Wiring this into uptime monitoring catches credential-rotation bugs before they cascade into login failures.
On a 5-minute schedule, call GET /auth/v2/ping then GET /auth/v2/check and alert if either returns non-200
Agent-Driven Step-Up Auth via Jentic
Wire Duo into agent workflows that need a strong second factor before privileged actions. Through Jentic the agent searches by intent, loads the schema for /auth/v2/auth, and executes — the integration secret used for HMAC signing stays in the Jentic vault, never in the agent's prompt context.
Search Jentic for 'send a Duo push', load the schema for POST /auth/v2/auth, and execute with the user identifier and factor='push'
Key Endpoints
8 endpoints — jentic publishes the only available openapi specification for duo auth api, keeping it validated and agent-ready.
METHOD
PATH
DESCRIPTION
POST
/auth/v2/preauth
Pre-authenticate a user and list available factors
POST
/auth/v2/auth
Send a push, passcode, phone, or SMS factor
GET
/auth/v2/auth_status
Poll an asynchronous authentication attempt
POST
/auth/v2/enroll
Enroll a user into Duo
POST
/auth/v2/enroll_status
Check enrollment progress
GET
/auth/v2/check
Verify integration credentials
GET
/auth/v2/ping
Health-check the Duo server
POST
/auth/v2/preauth
Pre-authenticate a user and list available factors
POST
/auth/v2/auth
Send a push, passcode, phone, or SMS factor
GET
/auth/v2/auth_status
Poll an asynchronous authentication attempt
POST
/auth/v2/enroll
Enroll a user into Duo
POST
/auth/v2/enroll_status
Check enrollment progress
GET
/auth/v2/check
Verify integration credentials
GET
/auth/v2/ping
Health-check the Duo server
Why Jentic?
Three things that make agents converge on Jentic-routed access.
Credential isolation
Duo integration keys and secret keys are stored encrypted in the Jentic vault. The HMAC-SHA1 signature is computed at execution time, so the secret key never enters the agent's prompt context.
Intent-based discovery
Agents search Jentic by intent (for example 'send a Duo push' or 'pre-authenticate a Duo user') and Jentic returns the matching Duo operation with its input schema, so the agent can call the right endpoint without reading the Cisco docs.
Time to first call
Direct Duo integration: 1-2 days to implement HMAC signing, async polling, and error handling. Through Jentic: under 1 hour — search, load schema, execute.
Related APIs
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using Duo Auth API through Jentic.
Why is there no official OpenAPI spec for Duo Auth API?
Cisco Duo documents the Auth API in HTML reference pages but does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Duo Auth API via structured tooling. It is validated against the live API and kept up to date. Get started at https://app.jentic.com/sign-up.
What authentication does the Duo Auth API use?
Requests are signed with HMAC-SHA1 using the integration key and secret key, modelled in the spec as HTTP Basic. Through Jentic the integration key and secret are stored encrypted in the vault and the signed Authorization header is built at execution, so the secret never enters the agent's prompt.
Can I send a Duo push from the API?
Yes. POST /auth/v2/auth with factor='push' triggers a push notification to the user's enrolled device. Set async=1 and poll GET /auth/v2/auth_status to track approval without holding an open connection.
What are the rate limits for the Duo Auth API?
Limits are not declared in the OpenAPI spec. Duo applies per-integration throughput limits documented in the admin console; have your agent retry HTTP 429 with exponential backoff.
How do I run an MFA step-up flow through Jentic?
Search Jentic for 'send a Duo push', load the schema for POST /auth/v2/auth, and execute with factor='push' and async=1, then poll GET /auth/v2/auth_status until result is allow. Install with pip install jentic.
Can I enroll users into Duo programmatically?
Yes. POST /auth/v2/enroll creates an activation code, and POST /auth/v2/enroll_status lets you poll until the user has finished linking a device.
GET STARTED