canonical: https://jentic.com/apis/duo.com/duo # Duo Auth API 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. ## For AI 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. ## Scope Does not handle SSO, password storage, or directory sync - use for Duo two-factor authentication and enrollment only. ## Capabilities - 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 ### 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. Example prompt: 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. Example prompt: 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. Example prompt: 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 your Jentic One instance, never in the agent's prompt context. Example prompt: 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 | 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 | ## Key resources - **Pre-Authentication** — Discover available factors for a user via POST /auth/v2/preauth - **Authentication** — Send a factor and check its status via /auth/v2/auth and /auth/v2/auth_status - **Enrollment** — Enrol a new user and poll progress via /auth/v2/enroll and /auth/v2/enroll_status - **Health** — Verify the integration via /auth/v2/ping and /auth/v2/check ## Why Jentic - **Setup:** Wiring the Duo Auth API by hand means computing an HMAC-SHA1 signature over each request from your integration and secret keys and pointing every call at your own tenant-specific api_hostname. Through Jentic you install once, import Duo from the API Directory, store the keys once, and your agent calls it. - **Permission scoping:** Duo takes the user and factor details in the request body, so you limit the agent to the operations it needs, such as sending a push or checking auth status. You choose which operations are allowed, so enrolling new devices is not included unless you add it. - **Credential handling:** Your Duo integration and secret keys are stored once, encrypted, by your own Jentic One instance, and the HMAC-SHA1 signature is computed at execution time. The secret key never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'send a Duo push' or 'pre-authenticate a Duo user', and Jentic returns the matching Duo operation with its input schema so the agent calls the right endpoint without reading the Cisco docs. ## Related APIs - **Okta API** — Identity platform with native MFA factors managed alongside SSO and lifecycle - **Auth0 Management API** — Identity platform with built-in MFA and broader social-login support than Duo - **Twilio Verify API** — OTP delivery via SMS, voice, and email without Duo's enterprise factor catalogue ## FAQ ### 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 with Jentic One, the self-hosted execution layer. ### 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. ### Can I limit what my agent is allowed to do with the Duo Auth API? Yes. Because Jentic One is self-hosted, you set the rules that decide which Duo operations and credentials your agent may use. You can allow only the operations the workflow needs, such as POST /auth/v2/auth to send a push and GET /auth/v2/auth_status to poll the result, while withholding others. Operations like POST /auth/v2/enroll to enroll a new device stay out of reach unless you explicitly grant them.