[Cisco Duo] Perform a real second-factor authentication: send a Duo Push, validate a passcode, place a phone callback, or send a new batch of SMS passcodes. THIS CONTACTS A REAL PERSON'S DEVICE AND HAS NO IDEMPOTENCY KEY. A duplicate call sends another push, places another call or sends another SMS batch, and consumes the user's authentication and lockout budget — repeated calls are an MFA-fatigue pattern. If a call times out after transmission its outcome is unknown: report the indeterminate state, do NOT replay it. Supply exactly one of userId or username. Grant access ONLY on a terminal result of "allow"; anything else, including errors and timeouts, denies. Factor "sms" deliberately returns "deny" after sending passcodes — re-prompt for a passcode afterwards. Set async to "1" to return immediately with a transaction id and poll duo_get_auth_status instead; the async response itself never grants access. MSP PARENT ACCOUNTS: pass accountId to target a subaccount instead of your own account — that subaccount's own Auth API application must first be stored on the Duo connection, because Duo's Auth API cannot authenticate another account's users.

[Cisco Duo] Validate the Auth API integration key, secret key and request signature, returning Duo's server time on success. This is the purpose-built credential test for the Auth API surface and needs no Duo permission grant. Failures are specific: a missing or malformed credential, an invalid integration key, an invalid signature, a missing timestamp, a host clock too far from Duo's server time, or an invalid content type. A 403 means the key belongs to a different Duo application type — most commonly Admin API keys entered where Auth API keys belong. MSP PARENT ACCOUNTS: pass accountId to target a subaccount instead of your own account — that subaccount's own Auth API application must first be stored on the Duo connection, because Duo's Auth API cannot authenticate another account's users.

[Cisco Duo] Create a new Duo user and issue activation material for a smartphone running Duo Mobile. Returns an activation barcode URL, activation code, activation URL, expiry, the new user's permanent id and the username. THE RETURNED ACTIVATION MATERIAL IS SECRET — treat it like a password and do not persist or echo it beyond the enrollment flow. This operation is NOT idempotent and has no idempotency key: if you omit username, Duo generates one, so a retry after an ambiguous failure can create a SECOND user. If you supply a username, a retry returns a duplicate-username error. Never retry this automatically. An effective New User Policy can block enrollment outright. For a landline or a phone that cannot run Duo Mobile, use duo_preauth's enrollment portal URL instead. MSP PARENT ACCOUNTS: pass accountId to target a subaccount instead of your own account — that subaccount's own Auth API application must first be stored on the Duo connection, because Duo's Auth API cannot authenticate another account's users.

[Cisco Duo] Download the logo stored on the Duo Auth API application. Duo returns PNG image data rather than JSON, so the image is uploaded to secure storage and this tool returns a short-lived read-only download URL along with the content type, suggested filename, size in bytes and expiry. A 404 means no logo is currently configured on the application.

[Cisco Duo] Long-poll for the next update to an asynchronous authentication started by duo_authenticate with async="1". If no update is ready, Duo holds the request until there is one. The result field is the ONLY polling control: keep polling while it is "waiting", and stop on a terminal "allow" (grant access) or "deny" (deny access). Transitions can be fast enough that intermediate statuses such as calling, answered or pushed are skipped entirely, so never require a particular status sequence and never infer access from the status message. For asynchronous verified push, the status message can carry the verification code and instructions to show the user. An error stating the long poll timed out waiting for an update is normal — poll again. MSP PARENT ACCOUNTS: pass the SAME accountId you passed to duo_authenticate — the transaction id was minted by that subaccount's own Auth API application and does not exist in any other account.

[Cisco Duo] Check whether activation material issued by duo_enroll_user has been claimed. The response value is a bare status string, not an object: "success" means the user added the account to Duo Mobile, "invalid" means the code expired or does not match the user, and "waiting" means it has not been claimed yet. Both "success" and "invalid" are terminal — stop polling. When polling "waiting", back off between calls and stop at the activation code's expiry; Duo publishes no recommended polling interval. MSP PARENT ACCOUNTS: pass accountId to target a subaccount instead of your own account — that subaccount's own Auth API application must first be stored on the Duo connection, because Duo's Auth API cannot authenticate another account's users.

[Cisco Duo] Check that the Duo service is reachable and return Duo's current server time as Unix seconds. This is the only Duo endpoint that needs no credentials and sends no signature, so it isolates a network/reachability problem from a credential problem. It validates NOTHING about your integration key, secret key, permissions or policy — use duo_check_integration for that. A successful ping followed by a failing duo_check_integration means the credentials or the host clock are wrong, not the network.

[Cisco Duo] Evaluate Duo policy for a user and, when a second factor is needed, return the devices and factors they may use. Call this only AFTER primary authentication has already succeeded in the protected application. Supply exactly one of userId or username — both, or neither, is invalid. The result drives the next step: "auth" means present the allowed factors and call duo_authenticate; "allow" means grant access now (policy, bypass or a trusted device satisfied Duo); "deny" means deny access; "enroll" means deny access and optionally offer the returned enrollment portal URL, which is valid for five minutes. Devices report capabilities such as auto, push, sms, phone and mobile_otp; hardware tokens report none. Avoid blind duplicate calls when requesting verified push — a response can issue a new transaction id and verification code that expire 60 seconds after issuance. MSP PARENT ACCOUNTS: pass accountId to target a subaccount instead of your own account — that subaccount's own Auth API application must first be stored on the Duo connection, because Duo's Auth API cannot authenticate another account's users.

[Cisco Duo] Create up to 100 Duo users in a single call, rate-limited by Duo to 50 calls per minute. IF ANY SINGLE USER CANNOT BE CREATED THE ENTIRE REQUEST FAILS and no users are created — so a validation problem in one row loses the whole batch. Check the error, fix that row, and resend. Supply a JSON object containing a users array; each entry needs username and may also carry realname, email, status, notes, firstname and lastname. Requires the Duo application's resource-write permission.

[Cisco Duo] Restore up to 100 users from Duo's Trash, rate-limited by Duo to 50 calls per minute. IF ANY SINGLE USER CANNOT BE RESTORED THE ENTIRE REQUEST FAILS and none are restored. Note that restoring does NOT re-enable anyone: restored users keep their disabled status and still cannot log in until you change their status with duo_modify_user. Only users sent to Trash can be restored — a user removed with duo_delete_user is gone permanently. Requires the Duo application's resource-write permission.

[Cisco Duo] Move up to 100 users to Duo's Trash, where they remain pending deletion for seven days and can be brought back with duo_bulk_restore_users. Trashed users cannot authenticate, so this immediately removes their access. UNLIKE the other two bulk operations this one can return PER-USER success and failure results in a single response — read every entry rather than trusting the overall status. Requires the Duo application's resource-write permission.

[Cisco Duo] Create a Duo user. Requires the Duo application's resource-write permission. Supply a JSON object; username is the only required field. Optional fields are alias1 through alias4 (or aliases), realname, firstname, lastname, email, status, notes, date_of_birth, enable_auto_prompt, and any custom attributes as custom_attributes.<name>. The new user has no enrolled devices yet — attach one with duo_associate_phone_with_user, or have them self-enroll with duo_enroll_user_via_email.

[Cisco Duo] PERMANENTLY delete a Duo user, IMMEDIATELY. This does NOT put the user in Duo's Trash and there is NO undo — the user and their device enrolments are gone, and re-creating them means enrolling their devices again. If you want the recoverable path, use duo_bulk_send_users_to_trash instead, which holds users for seven days and can be reversed with duo_bulk_restore_users. Requires the Duo application's resource-write permission.

[Cisco Duo] Create a Duo user and EMAIL THEM an enrolment link so they can enroll their own device. This sends real email to a real person and creates a user, so it is not repeatable without consequence — a second call for the same username fails on the duplicate, and a call with a wrong address emails a stranger. This is the ADMIN API enrolment: contrast duo_enroll_user, the Auth API tool, which returns activation material (a QR code and link) directly to the caller instead of emailing it — use that one when your own interface will present the enrolment. Requires the Duo application's resource-write permission.

[Cisco Duo] Get one Duo user by user id, including their status, aliases, real name, email, notes, group memberships and enrolled devices. Requires the Duo application's resource-read permission. Find the user id with duo_list_users. MSP PARENT ACCOUNTS: to read a user in a subaccount, pass accountId AND apiHostname from the same duo_list_subaccounts entry — the same parent Admin API credentials are used.

[Cisco Duo] Read the outcome of a verification push sent with duo_send_user_verification_push, using the push id that call returned. Poll this rather than re-sending the push. Requires the Duo application's resource-read permission. MSP PARENT ACCOUNTS: to read this in a subaccount, pass accountId AND apiHostname from the same duo_list_subaccounts entry — the same parent Admin API credentials are used.

[Cisco Duo] List the external directory synchronizations configured for the account (for example Active Directory or Azure AD), with their keys and status. You need a directory key from here to call duo_sync_user_from_directory. Requires the Duo application's resource-read permission.

[Cisco Duo] List or search Duo users. Requires the Duo application's resource-read permission. NOTE the page size here caps at 300, not the 500 most other Duo lists allow. Narrow the result with username (an exact match returning one user), email, or the userIdList / usernameList comma-delimited filters. The usernames and userIds parameters are DEPRECATED equivalents that Duo caps at 100 values and that make it IGNORE limit and offset entirely — prefer userIdList / usernameList. Page with limit plus offset and read metadata.next_offset to know whether more records remain. MSP PARENT ACCOUNTS: to list a subaccount's users instead of your own, pass accountId AND apiHostname from the same duo_list_subaccounts entry — the same parent Admin API credentials are used.

[Cisco Duo] Modify an existing Duo user. Requires the Duo application's resource-write permission. Supply a JSON object containing only the fields to change; anything you omit keeps its current value. Changeable fields are username, alias1 through alias4 (or aliases), realname, firstname, lastname, email, status, notes, date_of_birth, enable_auto_prompt, and custom_attributes.<name> entries. Changing status is how you enable, disable or bypass a user — a disabled user cannot authenticate.

[Cisco Duo] Send a verification push to one of a user's enrolled phones — typically to confirm the right person holds the device before a help-desk action. THIS SENDS A REAL PUSH NOTIFICATION to a real person's phone; repeated calls are how MFA-fatigue attacks work, so do not loop on it. The response returns a push id; read the outcome with duo_get_user_verification_push_response. Requires the Duo application's resource-write permission. MSP PARENT ACCOUNTS: to send this in a subaccount, pass accountId AND apiHostname from the same duo_list_subaccounts entry — the same parent Admin API credentials are used.

[Cisco Duo] Synchronize a single user from an external directory immediately, instead of waiting for the scheduled sync. Useful when someone's directory record just changed — a new group, a disabled account — and you need Duo to reflect it now. The user's Duo attributes and group memberships are overwritten from the directory, so directory state wins over anything set directly in Duo. Get the directory key from duo_list_directory_syncs. Requires the Duo application's resource-write permission.

[Cisco Duo] Add a user to a group. Because Duo policy is applied by group, this can immediately change which policies govern that user — including which factors they may use and whether they are allowed to authenticate at all. Get group ids from duo_list_groups. Requires the Duo application's resource-write permission.

[Cisco Duo] Attach an EXISTING phone record to a user, giving them the ability to authenticate with it. This does not create a phone — create one with duo_create_phone first, or find an existing id with duo_list_phones. A phone may be shared by more than one user. Requires the Duo application's resource-write permission.

[Cisco Duo] Attach an EXISTING hardware OTP token to a user so they can authenticate with its passcodes. This does not create a token — create one with duo_create_token or find an existing id with duo_list_tokens. Requires the Duo application's resource-write permission.

[Cisco Duo] Generate bypass codes for a user — one-time codes that let them authenticate WITHOUT a second factor, typically to recover a lost phone. THE RESPONSE CONTAINS THE CODES IN CLEAR TEXT: they are credentials that defeat MFA for that user, so hand them to the right person over a trusted channel and never log or retain them. BY DEFAULT THIS REPLACES the user's existing bypass codes, invalidating any already issued — pass preserveExisting to keep them. Supply either count (to have Duo generate codes) or codes (to set your own), not both. Requires the Duo application's resource-write permission.

[Cisco Duo] Remove a user from a group. Duo policy is applied by group, so this can change or remove the policies governing that user — potentially loosening restrictions rather than tightening them. Check duo_list_user_groups first to understand what the user will be left with. The group itself is not deleted. Requires the Duo application's resource-write permission.

[Cisco Duo] Detach a phone from a user, REMOVING THEIR ABILITY TO AUTHENTICATE with it. If it was their only enrolled device they may be locked out entirely, so check duo_list_user_phones first. The phone record itself is not deleted (use duo_delete_phone for that) and remains attached to any other users. Requires the Duo application's resource-write permission.

[Cisco Duo] Detach a hardware OTP token from a user, removing their ability to authenticate with it. If it was their only enrolled device they may be locked out, so check duo_list_user_tokens first. The token record itself is not deleted (use duo_delete_token for that). Requires the Duo application's resource-write permission.

[Cisco Duo] List metadata about a user's bypass codes — how many exist, when they expire and how many uses remain. This returns metadata, NOT the code values themselves; codes are only ever shown at the moment they are created. Requires the Duo application's resource-read permission. MSP PARENT ACCOUNTS: to read this for a user in a subaccount, pass accountId AND apiHostname from the same duo_list_subaccounts entry — the same parent Admin API credentials are used.

[Cisco Duo] List a user's Duo Desktop authenticators — the desktop devices registered for endpoint verification and offline access. Requires the Duo application's resource-read permission. MSP PARENT ACCOUNTS: to read this for a user in a subaccount, pass accountId AND apiHostname from the same duo_list_subaccounts entry — the same parent Admin API credentials are used.

[Cisco Duo] List the groups a user belongs to. Group membership drives Duo policy, so this is how you find out which policies apply to someone. Requires the Duo application's resource-read permission. MSP PARENT ACCOUNTS: to read this for a user in a subaccount, pass accountId AND apiHostname from the same duo_list_subaccounts entry — the same parent Admin API credentials are used.

[Cisco Duo] List the phones enrolled to a user, with each phone's id, number, type, platform and activation state. You need a phone id from here for duo_send_user_verification_push and for the phone SMS and activation tools. Requires the Duo application's resource-read permission. MSP PARENT ACCOUNTS: to read this for a user in a subaccount, pass accountId AND apiHostname from the same duo_list_subaccounts entry — the same parent Admin API credentials are used.

[Cisco Duo] List the hardware OTP tokens attached to a user, with each token's id, type and serial. Requires the Duo application's resource-read permission. MSP PARENT ACCOUNTS: to read this for a user in a subaccount, pass accountId AND apiHostname from the same duo_list_subaccounts entry — the same parent Admin API credentials are used.

[Cisco Duo] List a user's WebAuthn credentials — passkeys, security keys and platform authenticators such as Touch ID or Windows Hello. Unlike the other user sub-resources this endpoint takes no paging parameters and returns the full set. Requires the Duo application's resource-read permission. MSP PARENT ACCOUNTS: to read this for a user in a subaccount, pass accountId AND apiHostname from the same duo_list_subaccounts entry — the same parent Admin API credentials are used.

[Cisco Duo] Create a phone record. The phone is not usable yet: attach it to a user with duo_associate_phone_with_user, and for Duo Mobile also activate it with duo_create_phone_activation_code or duo_send_phone_sms_activation. Set type and platform accurately — the SMS activation and installation tools FAIL when either is unknown. Requires the Duo application's resource-write permission.

[Cisco Duo] Generate a Duo Mobile activation code and URL for a phone and RETURN them to you. THE RESPONSE IS SECRET: whoever holds the activation code can enrol that device as the user's second factor, so treat it like a password and do not log or retain it. Generating a new code INVALIDATES any previous unused code for the phone, which will break an activation the user has already started. This returns the material to you; to have Duo text it to the phone instead, use duo_send_phone_sms_activation. Requires the Duo application's resource-write permission.

[Cisco Duo] Delete a phone record. This removes it from EVERY user it is attached to, so anyone whose only enrolled device this was will be unable to authenticate. Check duo_get_phone first to see who is affected. To detach a phone from one user while keeping the record, use duo_disassociate_phone_from_user instead. Requires the Duo application's resource-write permission.

[Cisco Duo] Get one phone record by id, including its number, type, platform, activation state and the users it is attached to. Requires the Duo application's resource-read permission. MSP PARENT ACCOUNTS: to read a phone in a subaccount, pass accountId AND apiHostname from the same duo_list_subaccounts entry — the same parent Admin API credentials are used.

[Cisco Duo] List phone records in the account, with each phone's id, number, name, type, platform and activation state. Optionally filter by number or extension. Requires the Duo application's resource-read permission. Page size defaults to 100 and caps at 500. MSP PARENT ACCOUNTS: to list a subaccount's phones, pass accountId AND apiHostname from the same duo_list_subaccounts entry — the same parent Admin API credentials are used.

[Cisco Duo] Modify a phone record. Only the fields you supply change. Be aware that changing the number, type or platform can invalidate an existing Duo Mobile activation, which means the user must re-activate before they can use Duo Push again. Requires the Duo application's resource-write permission.

[Cisco Duo] Generate a Duo Mobile activation code and TEXT IT to the phone. THIS SENDS A REAL SMS TO A REAL PHONE NUMBER AND SPENDS TELEPHONY CREDITS — it cannot be recalled, and a wrong phone id texts activation material to the wrong person. It also invalidates any previous unused activation code. This FAILS if the phone's type or platform is unknown; fix those with duo_modify_phone first. SMS SIZE LIMITS: the whole message is capped at 160 characters and activation URLs run about 60, so keep custom text near 80 characters or the URL may be truncated. Requires the Duo application's resource-write permission.

[Cisco Duo] Text Duo Mobile installation instructions to a phone. THIS SENDS A REAL SMS AND SPENDS TELEPHONY CREDITS and cannot be recalled. It FAILS if the phone's type or platform is unknown. SMS SIZE LIMITS: the message is capped at 160 characters and installation URLs run 50-75, so keep custom text near 80 characters. This sends installation instructions only — to send an activation code as well, use duo_send_phone_sms_activation. Requires the Duo application's resource-write permission.

[Cisco Duo] Text a fresh batch of one-time passcodes to a phone. THIS SENDS A REAL SMS CONTAINING WORKING AUTHENTICATION CREDENTIALS AND SPENDS TELEPHONY CREDITS — it cannot be recalled, and a wrong phone id sends usable passcodes to the wrong person. Sending a new batch replaces any previous unused batch, so passcodes the user already has stop working. Requires the Duo application's resource-write permission.

[Cisco Duo] Register a hardware OTP token. Type and serial are required. The seed material — secret for HOTP tokens, or private_id and aes_key for YubiKeys — comes from the token vendor and IS SECRET: it is the cryptographic key that generates the token's passcodes, so handle it like a private key and never log it. The token is not usable until attached to a user with duo_associate_token_with_user. Requires the Duo application's resource-write permission.

[Cisco Duo] Delete a hardware OTP token. This removes it from EVERY user it is attached to, so anyone whose only enrolled device this was will be unable to authenticate. Re-registering it later means re-entering the vendor seed material. If the token merely stopped working, try duo_resync_token first — a counter drift is far more common than a genuine failure. To detach it from one user while keeping the record, use duo_disassociate_token_from_user. Requires the Duo application's resource-write permission.

[Cisco Duo] Get one hardware OTP token by id, including its type, serial and the users it is attached to. Requires the Duo application's resource-read permission.

[Cisco Duo] List hardware OTP tokens registered in the account, with each token's id, type and serial number. Optionally filter by type or serial. Requires the Duo application's resource-read permission. Page size defaults to 100 and caps at 500.

[Cisco Duo] Resynchronize a hardware OTP token whose counter has drifted out of step with Duo, which is the usual reason a physically working token stops being accepted. You must supply THREE CONSECUTIVE passcodes read from the device, in the order they appear. This is corrective rather than destructive — it restores the token to working order and does not invalidate it. Requires the Duo application's resource-write permission.

[Cisco Duo] Delete a WebAuthn credential — a passkey, security key or platform authenticator. THIS CANNOT BE UNDONE FROM DUO'S SIDE: re-registering requires the end user to enrol the physical device again in a browser, so if this was their only enrolled factor they will be locked out until they do. Check duo_get_webauthn_credential to confirm the owner first. Requires the Duo application's resource-write permission.

[Cisco Duo] Get one WebAuthn credential by its key, including its label, type and owning user. Requires the Duo application's resource-read permission.

[Cisco Duo] List WebAuthn credentials across the whole account — passkeys, security keys and platform authenticators such as Touch ID or Windows Hello — with each credential's key, label and owning user. For one specific user's credentials, use duo_list_user_webauthn_credentials instead. Requires the Duo application's resource-read permission. Page size defaults to 100 and caps at 500.

[Cisco Duo] Create a shared device authentication configuration, changing how members of the named groups authenticate on shared machines. BOTH list parameters are REQUIRED: the groups it applies to and the trusted-endpoint integrations it covers. Because this alters real authentication behavior for everyone in those groups, confirm the group ids with duo_list_groups first. Requires the Duo application's resource-write permission.

[Cisco Duo] Delete a Duo Desktop authenticator, removing that machine's registration. The user must re-register the device with Duo Desktop before endpoint verification or offline access works there again. Note that Duo returns success even when the record was already absent, which does NOT make this reversible. Requires the Duo application's resource-write permission.

[Cisco Duo] Delete a shared device authentication configuration. Everyone in the groups it covered reverts to their ordinary authentication behavior on shared machines, which may be more or less permissive than the configuration allowed — read duo_get_shared_device_auth_config first so you know what is being removed and can recreate it if needed. Requires the Duo application's resource-write permission.

[Cisco Duo] Get one Duo Desktop authenticator by its key, including the machine's details and owning user. Requires the Duo application's resource-read permission.

[Cisco Duo] Get one shared device authentication configuration by its shared-device key, including whether it is active and which groups and trusted-endpoint integrations it covers. Requires the Duo application's resource-read permission.

[Cisco Duo] List Duo Desktop authenticators — the desktop and laptop machines registered for endpoint verification and offline access. These are individual device registrations; the separate shared device authentication configurations are listed by duo_list_shared_device_auth_configs. Requires the Duo application's resource-read permission. Page size defaults to 100 and caps at 500.

[Cisco Duo] List shared device authentication configurations — the rules that control how members of particular groups authenticate on shared machines, each tied to a set of groups and trusted-endpoint integrations. This is a DIFFERENT resource from the individual desktop authenticators listed by duo_list_desktop_authenticators. Requires the Duo application's resource-read permission.

[Cisco Duo] Update a shared device authentication configuration. Only the fields you supply change. Toggling active switches the rule on or off for every covered group, and changing the group or trusted-endpoint lists REPLACES them rather than adding to them — read duo_get_shared_device_auth_config first so you send the full intended list. Requires the Duo application's resource-write permission.

[Cisco Duo] Invalidate a bypass code immediately. This is the right tool when a bypass code may have leaked, since a live code lets someone authenticate without a second factor. It is irreversible — the code cannot be reinstated, and the user will need a fresh one from duo_create_user_bypass_codes if they still need bypass access. Requires the Duo application's resource-write permission.

[Cisco Duo] Get one bypass code's metadata by id — its owning user, expiry and remaining uses. The code value itself is never returned; it is shown only at creation. Requires the Duo application's resource-read permission. MSP PARENT ACCOUNTS: to read this in a subaccount, pass accountId AND apiHostname from the same duo_list_subaccounts entry — the same parent Admin API credentials are used.

[Cisco Duo] List bypass code metadata across the whole account — which users hold codes, when they expire and how many uses remain. Useful for finding stale bypass codes that should be revoked, since a live bypass code lets someone authenticate WITHOUT a second factor. This returns metadata only: code values are shown once, at creation. To issue codes, use duo_create_user_bypass_codes. Requires the Duo application's resource-read permission. MSP PARENT ACCOUNTS: to read this in a subaccount, pass accountId AND apiHostname from the same duo_list_subaccounts entry — the same parent Admin API credentials are used.

[Cisco Duo] Create a new subaccount under this parent account and return the newly created account. The new subaccount comes with its own api_hostname, which its applications must be configured against. It is created on the parent's default edition and with no telephony credits — set those explicitly with duo_set_subaccount_edition and duo_set_subaccount_telephony_credits, both of which affect billing. Fails with 400 on an invalid or missing name. Requires an MSP-capable parent account and the Duo 'Grant accounts - Write' permission.

[Cisco Duo] Delete a subaccount from the system. THIS IS IRREVERSIBLE AND REMOVES AN ENTIRE CUSTOMER ACCOUNT — its users, applications, devices and policies go with it, and every application configured against that subaccount's api_hostname stops authenticating. Confirm the exact account_id with duo_list_subaccounts first: Duo returns 200 both when the account was deleted AND when it never existed, so a success response does NOT prove you removed the account you intended. If the subaccount is itself the parent of other subaccounts, Duo returns 409 and those children must be deleted first. Requires an MSP-capable parent account and the Duo 'Grant accounts - Write' permission.

[Cisco Duo] Get the Duo edition currently in effect for one subaccount, which determines both its feature set and its billing. The returned edition is one of PERSONAL (Duo Free), ENTERPRISE (Duo Essentials), PLATFORM (Duo Advantage) or BEYOND (Duo Premier). Requires an MSP-capable parent account and the Duo 'Grant accounts - Read' permission.

[Cisco Duo] Get the telephony credits currently available to one subaccount, returned as credits. Telephony credits are what SMS and phone-call authentications consume, so a subaccount at zero credits cannot use those factors. Check this before changing a balance with duo_set_subaccount_telephony_credits. Requires an MSP-capable parent account and the Duo 'Grant accounts - Read' permission.

[Cisco Duo] List the subaccounts belonging to this parent account, each with its account_id (a 20-character string), name, and api_hostname. Use the subaccount's own api_hostname — not the parent's — when configuring that subaccount's applications, and use its account_id for every other subaccount tool. To READ a subaccount's directory with these same parent credentials, pass BOTH that entry's account_id and its api_hostname as the accountId and apiHostname parameters of one of the FIFTEEN subaccount-capable read tools: duo_list_users, duo_get_user, duo_list_groups, duo_get_group, duo_list_group_members, duo_list_phones, duo_get_phone, duo_list_bypass_codes, duo_get_bypass_code, duo_list_user_groups, duo_list_user_phones, duo_list_user_tokens, duo_list_user_bypass_codes, duo_list_user_webauthn_credentials and duo_list_user_desktop_authenticators. Duo requires both, so those tools refuse an accountId given on its own. NO other Duo tool accepts these parameters — any other read (for example duo_list_tokens or duo_list_directory_syncs) always answers for the PARENT account, so do not treat its result as subaccount data. This is a read-only operation despite being sent as a POST, and takes no parameters. Requires an MSP-capable parent account and the Duo 'Grant accounts - Read' permission.

[Cisco Duo] Set the effective Duo edition for a subaccount. THIS CHANGES WHAT THE CUSTOMER IS BILLED FOR. Raising the edition increases their cost; LOWERING it removes the features that edition provided, which can immediately disable capabilities that live policies and applications depend on (for example, endpoint and Trust Monitor data are only available on the higher editions). Read the current value with duo_get_subaccount_edition before changing it. Requires an MSP-capable parent account and the Duo 'Grant accounts - Write' permission.

[Cisco Duo] Set the TOTAL number of telephony credits a subaccount will hold. THIS MOVES REAL CREDITS OUT OF THE PARENT ACCOUNT'S BALANCE: any increase is transferred from the parent, so setting a subaccount that holds 100 credits to 300 deducts 200 from the parent and adds them to the subaccount. The value is the total AFTER the transfer, NOT the amount to add — passing the amount you meant to add will usually reduce the subaccount's balance instead. Read the current balance with duo_get_subaccount_telephony_credits first; the response reports credits_added. Requires an MSP-capable parent account and the Duo 'Grant accounts - Write' permission.

[Cisco Duo] Create a group. The new group starts with no members and no policy attached, so it changes nothing until users are added to it and a policy targets it. Setting status to Bypass or Disabled at creation means every user later added to the group inherits that behaviour immediately. Returns 400 when a group with that name already exists. Requires the Duo 'Grant resource - Write' permission.

[Cisco Duo] Delete a group. THIS CHANGES WHICH POLICIES APPLY TO ITS MEMBERS: any policy targeted at this group stops applying to everyone in it, so users can silently fall back to a weaker or stronger policy than intended. Run duo_list_group_members first to see who is affected. Duo returns 200 both when the group was deleted AND when it did not exist, so a success does not prove the intended group was removed. Returns 400 when the group is managed by an external directory or is used by an SSO routing rule — in the routing-rule case the response includes the rule details. Requires the Duo 'Grant resource - Write' permission.

[Cisco Duo] Get one group's own attributes by id — name, description and authentication status. This deliberately does NOT include the group's members; call duo_list_group_members for those. Returns 404 when no group has that id. Requires the Duo 'Grant resource - Read' permission. MSP PARENT ACCOUNTS: to read this in a subaccount, pass accountId AND apiHostname from the same duo_list_subaccounts entry — the same parent Admin API credentials are used.

[Cisco Duo] List the members of a group, each as user_id and username. Because Duo policies are targeted at groups, this is the list of users a group-targeted policy actually applies to — check it before changing or deleting the group. Page size defaults to 100 and caps at 500 here (note this differs from duo_list_groups, which caps at 100); page with offset while the response metadata carries a next_offset. Returns 404 when no group has that id. Requires the Duo 'Grant resource - Read' permission. MSP PARENT ACCOUNTS: to read this in a subaccount, pass accountId AND apiHostname from the same duo_list_subaccounts entry — the same parent Admin API credentials are used.

[Cisco Duo] List groups, each with its group_id, name, description and authentication status (Active = members must complete secondary authentication, Bypass = members skip it after primary authentication, Disabled = members cannot authenticate). A name managed by directory sync also indicates its source directory. This list does NOT include members — use duo_list_group_members for those. Page size defaults to 100 and CAPS AT 100 (unlike most Duo lists), so page with offset while the response metadata carries a next_offset. Requires the Duo 'Grant resource - Read' permission. MSP PARENT ACCOUNTS: to read this in a subaccount, pass accountId AND apiHostname from the same duo_list_subaccounts entry — the same parent Admin API credentials are used.

[Cisco Duo] Update a group. Only the fields you supply change. CHANGING status TAKES EFFECT IMMEDIATELY FOR EVERY MEMBER: Bypass lets them all skip secondary authentication after primary authentication, and Disabled stops them all from authenticating at all — check duo_list_group_members first to see who is affected. Renaming a group can also break external tooling or SSO routing rules that reference it by name. Returns 404 when no group has that id. Requires the Duo 'Grant resource - Write' permission.

[Cisco Duo] Cancel a user's in-flight identity verification. THIS INVALIDATES THE OUTSTANDING ACCESS CODE: a user part-way through proofing cannot finish, and the whole flow must be started again with duo_start_identity_verification, which mints a new code and makes them redo the process. Read the required inquiry_id from duo_get_identity_verification_status first, and check the status while you are there — cancelling an already verified or failed verification is not useful. Returns 404 when Identity Verification is not configured for the account. Requires the Duo 'Grant identity verification - Write' permission.

[Cisco Duo] Get the current status of a user's most recent identity verification. status is one of created (initiated), started (the user has begun), expired, verified (identity confirmed), failed (identity NOT confirmed), canceled, or unknown (an unexpected error occurred). The record also carries inquiry_id — which duo_cancel_identity_verification requires — plus expires_at and updated_at. NOTE THE RESPONSE INCLUDES access_code, the code that lets someone proceed with proofing as this user; do not log or forward it. This is how you check progress: there is no polling endpoint, so call this tool again. Returns 404 when Identity Verification is not configured for the account, which is a configuration answer rather than a missing user. Requires the Duo 'Grant identity verification - Read' permission.

[Cisco Duo] Begin Duo Identity Verification for a user, generating the access_code the user must supply to be redirected to Persona for proofing. THE RESPONSE IS SECRET: whoever holds the access code can proceed through identity proofing as that user, so treat it like a password and do not log or retain it. The response also returns inquiry_id (Persona's id for this inquiry, which duo_cancel_identity_verification requires), expires_at, updated_at, and a status that is always 'created' here. This starts a real proofing flow for a real person. Returns 400 when the user is missing values for the attributes Identity Verification requires, and 404 when Identity Verification is not configured for the account. Requires the Duo 'Grant identity verification - Write' permission.

[Cisco Duo] Execute a list of user operations in one request. Duo runs them SERIALLY IN THE ORDER SUPPLIED, capped at 50 operations per request and 50 calls per minute. CRITICAL: THIS CAN PARTIALLY SUCCEED. The response is an array containing a result for EVERY operation, mixing successes and failures — you must read each element rather than trusting the overall HTTP status, because an HTTP 200 can still contain failed operations. Serial ordering also means an earlier operation's effect is visible to a later one, so order matters when operations touch the same user. Because the list can contain deletions and other irreversible changes, review it before sending; there is no dry-run and no rollback of the operations that already ran. Requires the Duo application's resource-write permission.

[Cisco Duo] Get one endpoint record by its endpoint key, including the device's detected posture and the users seen on it. A not-found result can mean either that no endpoint has that key or that the record was purged after a period of inactivity. Requires the Duo application's resource-read permission.

[Cisco Duo] List endpoint records — the devices Duo has observed authenticating, along with the posture it detected such as operating system and version, browser, disk-encryption, firewall and password state, and whether Duo Desktop was present. This is the inventory to query when you want to know what is actually authenticating against Duo and how healthy those devices are. Requires the Duo application's resource-read permission. Page size defaults to 100 and caps at 500. Note that endpoint records are purged after a period of inactivity, so a device that has not authenticated recently may be absent.

[Cisco Duo] Block ONE registered device by its device key, immediately denying it access to every application protected by a Duo policy that requires device registration. Reverse it with duo_unblock_device. A not-found result means no registered device has that key. Requires the Duo application's resource-write permission.

[Cisco Duo] Block SEVERAL registered devices at once. Each blocked device is immediately denied access to every application protected by a Duo policy that requires device registration, so this cuts off real people mid-session. Confirm the device keys against duo_list_registered_devices before sending, and reverse with duo_unblock_devices if you block the wrong ones. For a single device use duo_block_device. Requires the Duo application's resource-write permission.

[Cisco Duo] List only the BLOCKED registered devices. Each entry carries a blocked field where BLOCKED_REGISTRATION means the device is blocked from registering and FALSE means it is allowed. Use this to audit what is currently cut off before you unblock anything. Requires the Duo application's resource-read permission. Page size defaults to 100 and caps at 500.

[Cisco Duo] List registered devices — the devices enrolled through Duo's device-registration flow, which policies can require before granting access. Requires the Duo application's resource-read permission. Page size defaults to 100 and caps at 500. For only the blocked ones, use duo_list_blocked_devices.

[Cisco Duo] Unblock ONE registered device by its device key, restoring its access to applications that require device registration. The device retains its original registration data. This undoes a deliberate security action — check duo_list_blocked_devices first to understand why it was blocked. A not-found result means no BLOCKED device has that key. Requires the Duo application's resource-write permission.

[Cisco Duo] Unblock SEVERAL registered devices at once, RESTORING their access to applications that require device registration. This undoes a deliberate security action, so confirm with duo_list_blocked_devices which devices are blocked and why before unblocking in bulk — a device blocked in response to a compromise should not be restored casually. Unblocked devices keep their original registration data. Requires the Duo application's resource-write permission.

[Cisco Duo] Retrieve Trust Monitor security events — the authentications and registrations Duo itself flagged as anomalous, each with the reasons it was surfaced (for example a new country, new device, new factor, unusual network, or unrealistic geovelocity) and a link an administrator can use to triage it in the Duo Admin Panel. This is the best starting point for investigating suspicious access. Requires the Duo application's log-reading permission. TIME BOUNDS ARE REQUIRED AND ARE 13-DIGIT MILLISECOND timestamps, matching the v2 log endpoints rather than the account reports: mintime must be strictly less than maxtime. Page size here is smaller than most Duo lists — it defaults to 50 and caps at 200. Filter by type to narrow to denied anomalous authentications, bypass-status changes, or device registrations.

[Cisco Duo] Create a new Duo integration (application). Duo randomly generates the integration key and secret key and RETURNS BOTH IN THE RESPONSE — that response therefore carries live secret material, so handle it accordingly. Requires the "Grant applications" API permission. Cannot create non-generic Duo Single Sign-On applications; types "azure-ca" (Microsoft Azure Active Directory) and "microsoft-eam" (Microsoft Entra ID: External MFA) can never be created via API, and neither can any integration type that has reached Duo end of support. New integrations default to user_access NO_USERS, so no one can use the application until you grant access. A 400 means invalid or missing parameters, a one-to-many object limit was reached, an integration already exists with that name, or the calling Admin API integration lacks permission. Prefer this over the legacy duo_create_integration_v2, which has no user_access parameter.

[Cisco Duo] Permanently delete a Duo integration. IRREVERSIBLE — the Admin API cannot restore an integration deleted in error, and DELETING ONE CAN BLOCK USER LOGINS: remove Duo authentication from the protected product FIRST (uninstall the Duo software, or update the device or application settings so Duo is no longer in the authentication path). Requires the "Grant applications" API permission. Duo refuses with a 400 if you target the Admin API integration whose secret key signed this request. Cannot delete non-generic Duo Single Sign-On applications. Note that a 200 means the integration was deleted OR never existed — it is not proof that something was removed, so confirm with duo_get_integration beforehand.

[Cisco Duo] Get a single Duo integration (application) by its integration key. Returns the same fields as duo_list_integrations for that one record, including its type, attached policy key, user access setting and — for an Admin API integration — its adminapi_* permission grants. Requires the "Grant applications" API permission. The secret_key is MASKED to its last four characters; use duo_get_integration_secret_key for the full value. SSO parameters are returned only for generic Duo Single Sign-On applications. A 404 means no integration has that key.

[Cisco Duo] Retrieve an integration's FULL secret key (skey). THE RESPONSE CONTAINS LIVE SECRET MATERIAL — anyone holding an integration key plus this secret key can sign requests as that application, so treat it like a password: do not log it, echo it into a ticket, or persist it. This is a read: it reveals the existing secret and rotates nothing (use duo_modify_integration with reset_secret_key to rotate). Requires the "Grant applications" API permission. Does NOT work for SSO integrations. Duo publishes this operation only on its v1 path — there is no v2 or v3 equivalent. A 400 means no integration has that key; a 403 means the Admin API integration you are authenticating with may not view the target integration's secret key.

[Cisco Duo] Retrieve the existing client_secret for one client of an OAuth 2.0 Client Credentials integration. THE RESPONSE CONTAINS LIVE SECRET MATERIAL — it is that client's password. Do not log, echo or persist it. This is a read: it reveals the current secret and rotates nothing (duo_reset_oauth_client_secret rotates). Requires the "Grant applications" API permission. This OAuth path needs BOTH identifiers — the integration key AND the client id; the OIDC equivalent (duo_get_oidc_client_secret) takes only an integration key. A 400 means invalid parameters or no client with that client id; a 404 means no integration with that integration key.

[Cisco Duo] Retrieve the existing client_secret for a Generic OIDC Relying Party integration. THE RESPONSE CONTAINS LIVE SECRET MATERIAL — it is the relying party's password. Do not log, echo or persist it. This is a read: it reveals the current secret and rotates nothing (duo_reset_oidc_client_secret rotates). Requires the "Grant applications" API permission. This OIDC path takes ONLY the integration key — unlike duo_get_oauth_client_secret, there is no client id segment. A 404 means no integration has that integration key.

[Cisco Duo] List the integrations (applications) protected by Duo, one page at a time. Returns each integration's name, type, integration key, notes, greeting, attached policy key, user access setting, allowed groups, prompt/self-service flags, sensitivity level, compliance requirements, business and technical owners, and — for Admin API integrations — the adminapi_* permission grants and networks_for_api_access. Requires the "Grant resource - Read" API permission. Each secret_key is MASKED to its last four characters; use duo_get_integration_secret_key for the full value. SSO parameters come back only for generic Duo Single Sign-On applications. Page by re-calling with the next_offset value from the response metadata until it is no longer present.

[Cisco Duo] Modify an existing Duo integration — its name, notes, greeting, user access, allowed groups, attached policy, prompt settings, and (on Admin API integrations) its own API permissions. Requires the "Grant applications" API permission. SELF-LOCKOUT HAZARD: on an Admin API integration this call ADDS OR REMOVES that integration's adminapi_* permission grants and can set networks_for_api_access — INCLUDING ON THE VERY INTEGRATION THESE CREDENTIALS AUTHENTICATE WITH. Removing a grant from, or applying a network restriction to, the calling integration takes effect immediately and can then only be undone in the Duo Admin Panel, so verify the target integration key is not your own before sending permission changes. Two more sharp edges: setting reset_secret_key to 1 ROTATES the integration's secret key and returns the new value, which breaks every client still configured with the old one (Duo refuses this with a 400 for the integration whose keys signed the request); and passing a BLANK policy_key DETACHES the currently attached custom policy, changing which policy applies to real users. Cannot modify non-generic Duo Single Sign-On applications. A 404 means no integration has that key. Prefer this over the legacy duo_modify_integration_v2.

[Cisco Duo] ROTATE the client_secret for one client of an OAuth 2.0 Client Credentials integration and return the new value. THIS BREAKS EVERY CLIENT STILL USING THE OLD SECRET: the previous value stops working the moment this succeeds, and there is no undo and no way to recover it — each deployment must be reconfigured with the new secret. Have somewhere to put the new value before you call this, and use duo_get_oauth_client_secret if you only need to read the current one. Requires the "Grant applications" API permission. The response carries live secret material. This OAuth path needs BOTH the integration key AND the client id; the OIDC equivalent (duo_reset_oidc_client_secret) takes only an integration key. A 400 means invalid parameters or no client with that client id; a 404 means no integration with that integration key.

[Cisco Duo] ROTATE the client_secret for a Generic OIDC Relying Party integration and return the new value. THIS BREAKS THE RELYING PARTY UNTIL IT IS RECONFIGURED: the previous secret stops working the moment this succeeds, with no undo and no way to recover the old value. Have somewhere to put the new secret before you call this, and use duo_get_oidc_client_secret if you only need to read the current one. Requires the "Grant applications" API permission. The response carries live secret material. This OIDC path takes ONLY the integration key — unlike duo_reset_oauth_client_secret, there is no client id segment. A 404 means no integration has that integration key.

[Cisco Duo] LEGACY handler: create a new Duo integration through the older v2 endpoint. DUO ITSELF RECOMMENDS duo_create_integration (v3) instead, because only v3 carries the user_access parameter — on this legacy handler you cannot set ALL_USERS / NO_USERS / PERMITTED_GROUPS at all, and an empty groups_allowed simply allows every group. Duo randomly generates the integration key and secret key and RETURNS BOTH IN THE RESPONSE, so that response carries live secret material. Requires the "Grant applications" API permission. Cannot create non-generic Duo Single Sign-On applications; types "azure-ca" and "microsoft-eam" can never be created via API, and neither can any type that has reached Duo end of support. A 400 means invalid or missing parameters, a one-to-many object limit was reached, an integration already exists with that name, or the calling Admin API integration lacks permission.

[Cisco Duo] LEGACY handler: permanently delete a Duo integration through the older v2 endpoint. Use duo_delete_integration (v3) instead unless you are pinned to the legacy contract. IRREVERSIBLE — the Admin API cannot restore an integration deleted in error, and DELETING ONE CAN BLOCK USER LOGINS: remove Duo authentication from the protected product FIRST (uninstall the Duo software, or update the device or application settings so Duo is no longer in the authentication path). Requires the "Grant applications" API permission. Duo refuses with a 400 if you target the Admin API integration whose secret key signed this request. Cannot delete non-generic Duo Single Sign-On applications. Note that a 200 means the integration was deleted OR never existed — confirm with duo_get_integration_v2 beforehand.

[Cisco Duo] LEGACY handler: get a single Duo integration by its integration key through the older v2 endpoint. Use duo_get_integration (v3) instead unless you specifically need the legacy response shape, which omits the identity-verification and subaccount grant fields v3 returns. Requires the "Grant applications" API permission. The secret_key is MASKED to its last four characters; use duo_get_integration_secret_key for the full value. SSO parameters are returned only for generic Duo Single Sign-On applications. A 404 means no integration has that key.

[Cisco Duo] LEGACY handler: retrieve the existing client_secret for one client of an OAuth 2.0 Client Credentials integration through the older v2 endpoint. Use duo_get_oauth_client_secret (v3) instead. THE RESPONSE CONTAINS LIVE SECRET MATERIAL — it is that client's password, so do not log, echo or persist it. This is a read: it reveals the current secret and rotates nothing (duo_reset_oauth_client_secret_v2 rotates). Requires the "Grant applications" API permission. This OAuth path needs BOTH identifiers — the integration key AND the client id; the OIDC equivalent takes only an integration key. A 400 means invalid parameters or no client with that client id; a 404 means no integration with that integration key.

[Cisco Duo] LEGACY handler: retrieve the existing client_secret for a Generic OIDC Relying Party integration through the older v2 endpoint. Use duo_get_oidc_client_secret (v3) instead. THE RESPONSE CONTAINS LIVE SECRET MATERIAL — it is the relying party's password, so do not log, echo or persist it. This is a read: it reveals the current secret and rotates nothing (duo_reset_oidc_client_secret_v2 rotates). Requires the "Grant applications" API permission. This OIDC path takes ONLY the integration key — unlike the OAuth variant, there is no client id segment. A 404 means no integration has that integration key.

[Cisco Duo] LEGACY handler: list Duo integrations (applications) through the older v2 endpoint. Use duo_list_integrations (v3) instead unless you specifically need the legacy response shape — this is not a duplicate of it, the legacy response OMITS the adminapi_identity_verification_* and adminapi_subaccount_* grant fields that v3 returns, and legacy groups_allowed semantics differ (an empty list here simply means all groups are allowed, because the legacy surface has no user_access field). Requires the "Grant resource - Read" API permission. Each secret_key is MASKED to its last four characters; use duo_get_integration_secret_key for the full value. SSO parameters come back only for generic Duo Single Sign-On applications. Page by re-calling with the next_offset value from the response metadata until it is no longer present.

[Cisco Duo] LEGACY handler: modify an existing Duo integration through the older v2 endpoint. Use duo_modify_integration (v3) instead unless you are pinned to the legacy contract — this legacy body has NO user_access member, and its groups_allowed treats an empty string as "allow every group". Requires the "Grant applications" API permission. SELF-LOCKOUT HAZARD, identical to v3: on an Admin API integration this ADDS OR REMOVES that integration's adminapi_* permission grants and can set networks_for_api_access — INCLUDING ON THE VERY INTEGRATION THESE CREDENTIALS AUTHENTICATE WITH. That takes effect immediately and can then only be undone in the Duo Admin Panel, so verify the target integration key is not your own before sending permission changes. Two more sharp edges: reset_secret_key set to 1 ROTATES the secret key and returns the new value, breaking every client still configured with the old one (Duo refuses this with a 400 for the integration whose keys signed the request); and a BLANK policy_key DETACHES the currently attached custom policy, changing which policy applies to real users. Cannot modify non-generic Duo Single Sign-On applications. A 404 means no integration has that key.

[Cisco Duo] LEGACY handler: ROTATE the client_secret for one client of an OAuth 2.0 Client Credentials integration through the older v2 endpoint, returning the new value. Use duo_reset_oauth_client_secret (v3) instead. THIS BREAKS EVERY CLIENT STILL USING THE OLD SECRET: the previous value stops working the moment this succeeds, with no undo and no way to recover it — each deployment must be reconfigured with the new secret. Have somewhere to put the new value before you call this, and use duo_get_oauth_client_secret_v2 if you only need to read the current one. Requires the "Grant applications" API permission. The response carries live secret material. This OAuth path needs BOTH the integration key AND the client id. A 400 means invalid parameters or no client with that client id; a 404 means no integration with that integration key.

[Cisco Duo] LEGACY handler: ROTATE the client_secret for a Generic OIDC Relying Party integration through the older v2 endpoint, returning the new value. Use duo_reset_oidc_client_secret (v3) instead. THIS BREAKS THE RELYING PARTY UNTIL IT IS RECONFIGURED: the previous secret stops working the moment this succeeds, with no undo and no way to recover the old value. Have somewhere to put the new secret before you call this, and use duo_get_oidc_client_secret_v2 if you only need to read the current one. Requires the "Grant applications" API permission. The response carries live secret material. This OIDC path takes ONLY the integration key — there is no client id segment. A 404 means no integration has that integration key.

[Cisco Duo] Calculate the EFFECTIVE policy for one user and one application — what Duo will actually enforce for that pair, built from the top-most section of the entire stack of policies that applies to that integration. This is a read-only evaluation: it computes and explains, it changes nothing. Requires the "Grant resource - Read" API permission. This is the right tool for "why is this user being asked for X on this app?": the response's source_policies list is ordered by precedence with the winning policy first, each entry naming its policy_key, policy_name and policy_type (global, application or group), and every section in the resulting policy carries the source_policy_key it came from. A 400 means invalid or missing parameters.

[Cisco Duo] Copy an existing policy into one or more NEW custom policies carrying the same settings. Requires the "Grant resource - Write" API permission. The copies are applied nowhere, so this is the safe way to branch a policy — no user's access changes until you apply one with duo_update_policy. Policy names do not have to be unique, so repeating a name simply creates another policy with that name rather than failing. A 404 means the source policy key does not exist; a 400 means invalid or missing parameters.

[Cisco Duo] Create a new custom policy and return its new policy key. Requires the "Grant resource - Write" API permission. Policy names do not have to be unique. Creating a policy with sections only is inert — it changes nobody's access until it is applied — so the safe pattern is to create it, read it back with duo_get_policy, and then apply it with duo_update_policy. If you DO pass the apply blocks here they take effect immediately on real users, and one member is especially blunt: affect_all_apps set to anything other than "inactive" (replace-policy, apply-policy or unassign-policy) CHANGES EVERY APPLICATION IN THE ACCOUNT. Which sections you may set depends on the Duo edition — Essentials supports a subset, Advantage and Premier progressively more. Any key you omit inside a section you do enable takes its default value. A 400 means invalid or missing parameters.

[Cisco Duo] Delete an entire custom policy. Requires the "Grant resource - Write" API permission. IMMEDIATE AND PERMANENT — Duo removes the policy outright and the Admin API cannot restore it. Every application and group it was applied to falls back to whatever policy remains in the stack (ultimately the global policy), so this silently CHANGES REAL USERS' AUTHENTICATION REQUIREMENTS, potentially loosening them. Check duo_get_policy_summary for everywhere the policy is applied before deleting, and consider duo_copy_policy first to keep a copy of its settings. If you only want to remove PART of a policy, use duo_update_policy with sectionsToDeleteJson instead. A 404 means the policy does not exist.

[Cisco Duo] Get the account's GLOBAL policy with all of its section data. This is a separate Duo endpoint from duo_get_policy and takes no parameters. Requires the "Grant resource - Read" API permission. The global policy is the base of every policy stack — it applies to all applications and users unless an application or group policy overrides a section — so read it first when working out why a user is being prompted a certain way. Its is_global_policy is true, its policy_key cannot be changed, its policy_name is "Global Policy", and unlike a custom policy its sections can NEVER be removed (duo_update_policy's sections_to_delete is rejected for it).

[Cisco Duo] Get one policy by its policy key, including all of its section data and the applications and groups it is applied to. Requires the "Grant resource - Read" API permission. A policy key is 20 alphanumeric characters starting with "PO" — get one from duo_get_policy_summary, duo_list_policies, an integration's policy_key, or the Duo Admin Panel's Policies page. To read the account's global policy use duo_get_global_policy, which is its own dedicated endpoint. Which sections appear depends on the Duo edition: Essentials exposes authentication_methods, authentication_policy, authorized_networks, duo_desktop, new_user, remembered_devices and trusted_endpoints; Advantage and Premier expose all sections with progressively more options. A 404 means no policy has that key.

[Cisco Duo] Summarize every policy in the account: each policy's name and key, the total policy_count, and exactly where each one is applied — the applications (by app_name and app_integration_key), whether it is attached to the whole application or to groups within it (apply_type of app or group_app), the group stacking order, and the groups themselves. This is the fastest way to answer "which policy applies where" before changing anything. Requires the "Grant resource - Read" API permission. It takes no parameters and CANNOT be paged: if response_is_truncated comes back true the account has more policy data than one response can carry, so fall back to duo_list_policies with paging. Also check the warnings field for non-fatal problems.

[Cisco Duo] List policies with their COMPLETE section data — every enabled section and all of its keys and values, plus policy_key, policy_name, is_global_policy, created_at and updated_at (both Unix timestamps, and both blank for policies untouched since November 2023) and policy_applies_to. Requires the "Grant resource - Read" API permission. Because each record carries all of its sections, Duo pages this endpoint much more tightly than its other lists: the default is 50 records and the MAXIMUM IS 100, not 500. Page through with the next_offset value from the response metadata. For a lighter "which policy is applied where" view, use duo_get_policy_summary instead.

[Cisco Duo] BULK-update policy section data across many policies at once — or across EVERY policy in the account. Requires the "Grant resource - Write" API permission. FLEET-WIDE BLAST RADIUS: with edit_all_policies set to true in policiesToUpdateJson the change lands on every policy the account has, and sections_to_delete in policyChangesJson REMOVES those sections from each targeted policy. Both alter live authentication requirements for real users the moment the call succeeds, and neither is undoable through this API — there is no revision history to roll back to. Read the current state first (duo_list_policies, or duo_get_policy_summary for the applied-where view), and prefer duo_update_policy on one key when you do not genuinely need the fleet-wide form. Sections can never be removed from the global policy. The response returns the updated policies. A 400 means invalid or missing parameters.

[Cisco Duo] Update ONE policy: rename it, change its section data, and change where it is applied. Requires the "Grant resource - Write" API permission. Every body member is optional and a call with none simply returns the policy unchanged; adding a section enables it with the values you send and defaults for the rest, while modifying an existing section changes only the keys you send. CHANGES LIVE ACCESS: this policy governs how real users authenticate, and several members are blunt instruments — sectionsToDeleteJson REMOVES sections outright (never permitted on the global policy), affect_all_apps set to anything other than "inactive" touches EVERY application in the account, replace_list REMOVES the policy from any application absent from the list, an empty replace_group_policies_list UNASSIGNS every group, and unassign_all drops all of this policy's group assignments. None of it is undoable through this API. Read the policy with duo_get_policy first and change one thing at a time. A 404 means the policy key does not exist.

[Cisco Duo] Get the account's Duo Passport configuration. Requires the "Grant resource - Read" API permission. Returns enabled_status — one of "disabled" (off for all users), "enabled" (on for all users), "enabled-for-groups" (on for selected groups), or the DEPRECATED "enabled-with-exceptions" (on for everyone except selected groups) — plus enabled_groups, the deprecated disabled_groups (each group carrying group_id and group_name), and custom_supported_browsers, which lists extra browsers Passport supports beyond the defaults as macOS Apple Team IDs (team_id) and Windows code-signing common names (common_name). Always call this before duo_modify_passport_config: that write replaces the whole object, so you need the current values to send back.

[Cisco Duo] Change the account's Duo Passport configuration — its enabled status and the groups it applies to. Requires the "Grant resource - Write" API permission. ACCOUNT-WIDE AND A WHOLE-OBJECT REPLACEMENT, NOT A PATCH: Duo documents enabledStatus, enabledGroupsJson and customSupportedBrowsersJson as required, so anything you leave out is replaced rather than preserved. ALWAYS call duo_get_passport_config first and send its values back with only your intended change applied, or you will silently wipe the group list or the custom browser list. The effect is immediate and reaches every user: switching to "disabled", or narrowing "enabled-for-groups", ends Passport session sharing for those users and forces them to authenticate again in each application. A 400 means invalid or missing parameters.

[Cisco Duo] Clear the "Expired" status Duo applies to an administrator who has been inactive too long. Needs the Duo "Grant administrators - Write" permission. The administrator reverts to whatever status they held before expiring, which restores Duo Admin Panel access when that status is "Active". Nothing is deleted. This is the ONLY way to clear "Expired" — duo_modify_admin's status accepts only "Active" or "Disabled". For an administrator locked out by failed logins rather than inactivity, use duo_reset_admin_auth_attempts. A 404 means no administrator has that admin_id.

[Cisco Duo] Create a new Duo Admin Panel administrator. Needs the Duo "Grant administrators - Write" permission. THE ROLE DEFAULTS TO "Owner": if you omit both role and roleId, this grants the new person FULL control of the Duo account, including the ability to change policy and delete other administrators — always pass an explicit roleId unless an Owner is genuinely intended. SENDS REAL EMAIL when sendEmail is "1": Duo emails the activation link and an introductory message to the address you supply and that cannot be recalled; with "0" (the default) the link is returned to this caller only. A 400 means invalid parameters, an email address already in use by another administrator, or a role that may not be restricted by an administrative unit. Duo's deprecated password and password_change_required body fields are not exposed here — a new administrator has no password until they activate; use duo_modify_admin_password_mgmt afterwards if you manage passwords externally.

[Cisco Duo] Create an ACCOUNT-LEVEL pending activation: a link to the Duo activation form for a BRAND-NEW administrator identified only by their EMAIL ADDRESS. Needs the Duo "Grant administrators - Write" permission. This is the invite-by-email surface and returns an admin_activation_id that duo_list_admin_activations and duo_delete_admin_activation use — it is NOT duo_create_admin_activation_link, which requires an admin_id for an administrator record that already exists. THE ROLE DEFAULTS TO "Owner": omitting both adminRole and adminRoleId means whoever completes that form becomes a full-control Owner of the Duo account, so pass an explicit adminRoleId unless an Owner is genuinely intended. SENDS REAL EMAIL when sendEmail is "1", which cannot be recalled; with "0" (the default) the link is returned to this caller only. The response carries the activation link and code — credential-grade material that must not be logged or stored. A 400 means invalid parameters or that the email address already belongs to an administrator or an existing pending activation.

[Cisco Duo] Create a PER-ADMIN activation link for an administrator record that ALREADY EXISTS and is in the "Pending Activation" status, identified by admin_id. Needs the Duo "Grant administrators - Write" permission. Do not confuse this with duo_create_admin_activation, which is the ACCOUNT-LEVEL surface that invites a brand-new administrator by EMAIL ADDRESS and returns an admin_activation_id: this tool needs an existing admin_id and issues that one administrator's link. Duo refuses with a 400 if a link already exists for the admin or the admin is not in a state that can be activated — delete the old link first with duo_delete_admin_activation_link. Creating a link does NOT email it; use duo_email_admin_activation_link for that. The link is credential-grade material for an Admin Panel account, so do not log or store it.

[Cisco Duo] Permanently delete a Duo Admin Panel administrator. Needs the Duo "Grant administrators - Write" permission. THIS IS IRREVERSIBLE — the administrator record, their role assignments and their administrative-unit memberships are gone and the person immediately loses Admin Panel access. Confirm the target with duo_get_admin before calling, and prefer setting status to "Disabled" via duo_modify_admin when the intent is a reversible suspension. Duo returns 200 whether the administrator was deleted OR never existed, so a success is not proof this call did the deleting. Administrators managed by directory sync cannot be deleted through the API (Duo returns 400) — remove them at the source directory instead.

[Cisco Duo] Delete an ACCOUNT-LEVEL pending administrator activation, cancelling that invitation. Needs the Duo "Grant administrators - Write" permission. IRREVERSIBLE: the link stops working, so anyone who received it can no longer complete activation and a fresh invitation must be created with duo_create_admin_activation. This is keyed by admin_activation_id from duo_list_admin_activations — to invalidate the per-admin link of an administrator record that already exists, use duo_delete_admin_activation_link with its admin_id instead. Duo returns 200 whether the activation was deleted OR never existed, so a success is not proof this call did the deleting; a 404 means the admin_activation_id was malformed.

[Cisco Duo] Delete and INVALIDATE an existing administrator's current per-admin activation link. Needs the Duo "Grant administrators - Write" permission. IRREVERSIBLE: every copy of that link already emailed or shared stops working immediately, so an administrator part-way through activation is stranded until you issue a new link with duo_create_admin_activation_link. This does NOT delete the administrator record (use duo_delete_admin) and is NOT the account-level surface — to cancel an invitation created by duo_create_admin_activation, use duo_delete_admin_activation with its admin_activation_id. A 400 means the administrator is not in a state that can be activated; a 404 means the admin_id is invalid.

[Cisco Duo] Email an existing administrator's CURRENT per-admin activation link to them. Needs the Duo "Grant administrators - Write" permission. THIS SENDS REAL EMAIL TO A REAL PERSON AND CANNOT BE RECALLED — every call sends another message, so do not retry it just because a response was slow. It acts on the per-admin surface keyed by admin_id, NOT the account-level activations surface (duo_create_admin_activation), and it does not create a link: if none exists, create one with duo_create_admin_activation_link first. The response echoes the activation code and expiry — secret material that must not be logged or stored. A 400 means the administrator is not in a state that can be activated; a 404 means the admin_id is invalid.

[Cisco Duo] Retrieve one Duo Admin Panel administrator by admin_id. Needs the Duo "Grant administrators - Read" (or "Grant administrators - Write") permission. Returns the same shape as duo_list_admins for a single administrator: name, email, status, role and role_id, restricted_by_admin_units, the administrative units they are assigned to, last_login, last_directory_sync, password_change_required, attached hardware tokens, phones and WebAuthn credentials. A 404 means no administrator has that admin_id. Use duo_list_admins to discover admin_id values.

[Cisco Duo] List the ACCOUNT-LEVEL pending administrator activations — the queue of outstanding invitations created by duo_create_admin_activation — one page at a time. Needs the Duo "Grant administrators - Read" (or "Grant administrators - Write") permission. Each entry carries admin_activation_id, the invited email address and the link's expiry timestamp; admin_activation_id is what duo_delete_admin_activation consumes. This lists INVITATIONS, not administrators — use duo_list_admins for administrator records, including those already in the "Pending Activation" status. Keep calling with a larger offset while the response metadata still returns next_offset. NOTE: an integration holding "Grant administrators - Write" also receives each activation code, which is secret material — do not echo, log or store it. A 400 means invalid paging parameters.

[Cisco Duo] List the administrators who can sign in to the Duo Admin Panel, one page at a time. Needs the Duo "Grant administrators - Read" (or "Grant administrators - Write") permission plus "Grant resource - Read" for the nested phone and hardware-token detail; a 403 means the integration key is valid but lacks that grant. Each record carries admin_id, name, email, status ("Active", "Disabled", "Expired" or "Pending Activation"), role and role_id, restricted_by_admin_units, admin_units, last_login, last_directory_sync and the admin's phones and WebAuthn credentials. Keep calling with a larger offset while the response metadata still returns next_offset. NOTE: if the integration holds "Grant administrators - Write", rows for administrators pending activation also include a live activation_url — that is credential-grade material for an Admin Panel account, so do not echo, log or store it. Duo's legacy role field is being replaced by role_id; prefer role_id.

[Cisco Duo] Change an existing administrator's name, phone, role, account status, administrative-unit restriction or hardware token. Needs the Duo "Grant administrators - Write" permission. THIS CAN REMOVE SOMEONE'S ACCESS: setting status to "Disabled" locks that administrator out of the Duo Admin Panel, and lowering role or roleId strips privileges they currently rely on — confirm the intended target with duo_get_admin first. Only "Active" and "Disabled" are valid statuses, and administrators with the "Owner" role cannot be disabled through the API; to clear an "Expired" status caused by inactivity use duo_clear_admin_expiration instead. Fields left unspecified are not changed. For an administrator managed by directory sync, Duo treats name, role, roleId, status and the subaccount roles as read-only. A 400 means invalid parameters or a role that may not be restricted by an administrative unit; a 404 means no administrator has that admin_id. Duo's deprecated password field is not exposed here — use duo_modify_admin_password_mgmt to set a password.

[Cisco Duo] Clear an administrator's failed-login counter, which UNLOCKS an administrator who was disabled by too many failed authentication attempts and lets them sign in to the Duo Admin Panel again. Needs the Duo "Grant administrators - Write" permission. Nothing is deleted and no other property changes — this only zeroes the failure count. It does NOT clear an "Expired" status from inactivity (use duo_clear_admin_expiration) and does NOT re-enable an administrator whose status was deliberately set to "Disabled" (use duo_modify_admin with status "Active"). A 404 means no administrator has that admin_id.

[Cisco Duo] Retrieve which secondary authentication factors administrators are currently permitted to use when signing in to the Duo Admin Panel. Needs the Duo "Grant administrators - Read" (or "Grant administrators - Write") permission. Returns a true/false flag per factor — push_enabled, verified_push_enabled, mobile_otp_enabled, sms_enabled, voice_enabled, hardware_token_enabled, yubikey_enabled and webauthn_enabled — plus verified_push_length, which is null when verified push is off. ALWAYS call this before duo_restrict_admin_auth_factors: that write replaces the entire set, so you need the current values to avoid silently disabling a factor administrators depend on. This setting is account-wide and is not the same as the Duo policy that governs end users.

[Cisco Duo] Retrieve one administrator's external password management configuration by admin_id. Needs the Duo "Grant administrators - Read" (or "Grant administrators - Write") permission. Returns whether has_external_password_mgmt is enabled for that administrator, meaning their Duo Admin Panel password may be set through the API. No password material is returned. This is the per-administrator form of duo_list_admin_password_mgmt, which is the account-wide list. A 404 means no administrator has that admin_id.

[Cisco Duo] List every administrator with a flag showing whether their Duo Admin Panel password is managed externally, one page at a time. Needs the Duo "Grant administrators - Read" (or "Grant administrators - Write") permission. Each row carries admin_id, email and has_external_password_mgmt: true means the password may be set through the API by duo_modify_admin_password_mgmt, false (Duo's default) means the administrator manages it themselves. No password material is returned. Keep calling with a larger offset while the response metadata still returns next_offset. For a single administrator use duo_get_admin_password_mgmt. A 400 means invalid paging parameters.

[Cisco Duo] Enable or disable external password management for one administrator, and/or SET THAT ADMINISTRATOR'S DUO ADMIN PANEL PASSWORD. Needs the Duo "Grant administrators - Write" permission. THIS IS THE MOST SENSITIVE WRITE ON THE DUO ADMINISTRATOR SURFACE: changing the password immediately invalidates the one that human currently knows and can cut off their access until the new value is delivered to them out of band. Never log, echo or store the password you send. Duo accepts a password only while external password management is enabled for that administrator — either set hasExternalPasswordMgmt true in this same call or have set it previously; otherwise it returns 400. Duo also changes password_change_required as a side effect: enabling external management forces it to false, and disabling external management forces it to true so the administrator must move off the externally-known password. Passwords must be at least twelve characters, may need a character mix per your Admin Password Policy, and are checked against common passwords and account information. A 404 means no administrator has that admin_id.

[Cisco Duo] RESTRICT which secondary authentication factors administrators may use to sign in to the Duo Admin Panel. Needs the Duo "Grant administrators - Write" permission. THIS REPLACES THE WHOLE SET — ANY FACTOR NOT EXPLICITLY SET TO TRUE IS DISABLED. A WRONG CALL HERE CAN LOCK EVERY ADMINISTRATOR OUT OF THE DUO ADMIN PANEL, including you, and recovering from that needs Duo Support. The safe procedure is: call duo_get_admin_auth_factors, then re-send true for every factor that must stay permitted plus the one you are adding, and only restrict to factors the administrators have actually enrolled. Duo requires at least one factor to be true, so an all-false call is rejected before it is sent. verifiedPushLength is accepted only while verifiedPushEnabled is true. Before any restriction has ever been applied, administrators may use any available two-factor method. This is account-wide and applies to Admin Panel logins, not to end-user application logins. A 400 means invalid or missing parameters, most often that no valid factor was specified.

[Cisco Duo] Sync ONE administrator, identified by email address, against a single configured admin directory sync — creating them, updating them, or marking them for deletion according to what the source directory (Active Directory, OpenLDAP or Entra ID) now says. Needs the Duo "Grant administrators - Write" permission. The change comes from the directory, so this can alter an existing administrator's name, role or status, or mark them for removal, without you specifying any of it. Administrators with the "Owner" role cannot be synced. Find directoryKey in the Duo Admin Panel under Users > Administrators > Admin Directory Sync by opening the configured directory. A 404 means the email or directoryKey was wrong, the administrator is not managed by that directory, or they are not in a source group named by the sync configuration; a 429 means Duo throttled the request, so retry later rather than immediately.

[Cisco Duo] Retrieve assignment detail for one administrative role, standard or custom, by role_id. Needs the Duo "Grant administrators - Read" permission. On top of the role's name, description and is_custom flag this returns who holds it: an admins list of admin_id, email and name, plus admin_sync_groups naming the external directory groups (directory_key and group_name) that assign this role to synced administrators. That makes it the way to answer "who has this level of access" before changing or retiring a role. A 404 means no role has that role_id — enumerate valid values with duo_list_admin_roles.

[Cisco Duo] List every administrative role in the Duo account — the eight standard roles (owner, service_manager, application_manager, user_manager, security_analyst, help_desk, billing, read_only) and any custom roles. Needs the Duo "Grant administrators - Read" permission plus "Grant resource - Read"; a 403 means the integration key is valid but lacks that grant. Each entry carries role_id, name, description, is_custom, and in_use showing whether any administrator currently holds the role. USE THIS FIRST to resolve the roleId you pass to duo_create_admin, duo_modify_admin or duo_create_admin_activation — a custom role can only be assigned by its role_id, never by the legacy role name. Duo documents no paging on this endpoint, so it returns the full set. Roles cannot be created, changed or deleted through the API; that is Duo Admin Panel work.

[Cisco Duo] Assign an administrator to an administrative unit, WIDENING what that administrator can see by adding this unit's groups and applications to their scope. Needs the Duo "Grant administrators - Write" permission. Both ids go in the path and no other parameters are sent. The administrator must ALREADY have restricted_by_admin_units set to true — set it with duo_modify_admin first, otherwise Duo returns 400, which is also what an invalid admin_unit_id or admin_id returns. The response is the resulting unit detail. The paired removal is duo_remove_admin_from_admin_unit.

[Cisco Duo] Assign a Duo user group to an administrative unit, so every administrator restricted to that unit can see the group's users. Needs the Duo "Grant administrators - Write" permission. Both ids go in the path and no other parameters are sent. This WIDENS the visibility of those administrators — it does not change the group or its members. The response is the resulting unit detail. A 400 means an invalid admin_unit_id or group_id. The paired removal is duo_remove_group_from_admin_unit.

[Cisco Duo] Assign an application (integration) to an administrative unit, so every administrator restricted to that unit can see and manage it. Needs the Duo "Grant administrators - Write" permission. Both the unit id and the integration_key go in the path and no other parameters are sent. This WIDENS those administrators' visibility — the application's own configuration is untouched. The response is the resulting unit detail. A 400 means an invalid admin_unit_id or integration_key. The paired removal is duo_remove_integration_from_admin_unit.

[Cisco Duo] Create an administrative unit, optionally seeding the administrators, Duo groups and applications it scopes. Needs the Duo "Grant administrators - Write" permission. The name must be unique across all administrative units. Every administrator you list must ALREADY have restricted_by_admin_units set to true — set that first with duo_modify_admin, or Duo rejects the assignment. Assigning an administrator here immediately narrows them to only this unit's groups and applications, so seed the groups and integrations in the same call, or right afterwards, to avoid leaving them able to see nothing. A 400 means invalid or missing parameters, or that a unit with that name already exists.

[Cisco Duo] Delete an administrative unit. Needs the Duo "Grant administrators - Write" permission. THIS IS IRREVERSIBLE and it changes what real administrators can see: every administrator who belonged ONLY to this unit keeps restricted_by_admin_units set to true and is left scoped to nothing, so they see no users and no applications in the Duo Admin Panel. Call duo_get_admin_unit first to read the unit's admins list, then either assign each of them another unit or clear their restriction with duo_modify_admin. The groups and applications the unit referenced are NOT deleted. Duo returns 200 whether the unit was deleted OR never existed, so a success is not proof this call did the deleting.

[Cisco Duo] Retrieve full detail for one administrative unit by admin_unit_id, including its members: the admins (by admin_id), groups (by group_id) and integrations (by integration_key) assigned to it, plus its name, description, restrict_by_groups and restrict_by_integrations flags. Needs the Duo "Grant administrators - Read" (or "Grant administrators - Write") permission. ALWAYS call this before changing or deleting a unit — the add, remove and delete tools report the resulting state but give you no before-and-after, and the admins list is what tells you who would be left scoped to nothing. A 404 means no unit has that admin_unit_id.

[Cisco Duo] List the administrative units that scope what restricted administrators can see in the Duo Admin Panel, one page at a time. Needs the Duo "Grant administrators - Read" (or "Grant administrators - Write") permission. Each entry carries admin_unit_id, name, description, restrict_by_groups and restrict_by_integrations. Optionally narrow the list to the units containing one administrator, one Duo group or one application by passing AT MOST ONE of adminId, groupId or integrationKey — passing more than one is rejected before the call is made, and Duo returns 404 when nothing is associated with the value given. Keep calling with a larger offset while the response metadata still returns next_offset. For the members of a unit, use duo_get_admin_unit.

[Cisco Duo] Change an administrative unit's name, description, restriction flags and/or assigned administrators, groups and applications. Needs the Duo "Grant administrators - Write" permission. THIS CHANGES WHAT REAL ADMINISTRATORS CAN SEE, so read the current state with duo_get_admin_unit first. The admins, groups and integrations lists are ADDITIVE — Duo assigns additional members and there is no remove-by-list here; take members out with duo_remove_admin_from_admin_unit, duo_remove_group_from_admin_unit or duo_remove_integration_from_admin_unit. CAUTION on the two restriction flags: Duo's own documentation gives them a default of false even on this modify call, so send restrictByGroups and restrictByIntegrations explicitly whenever the unit relies on either being true, rather than risking a silent reset that widens or narrows visibility. Every administrator you add must already have restricted_by_admin_units set to true. A 400 means invalid parameters or that no unit exists with that admin_unit_id.

[Cisco Duo] Unassign an administrator from an administrative unit, NARROWING what that administrator can see. Needs the Duo "Grant administrators - Write" permission. Both ids go in the path and no other parameters are sent. WATCH THE LAST-UNIT CASE: the administrator keeps restricted_by_admin_units set to true, so if this was the only unit they belonged to they can then see NO users and NO applications at all in the Duo Admin Panel. Check duo_list_admin_units with adminId first, and afterwards either assign another unit or set restricted_by_admin_units back to false with duo_modify_admin. The administrator account itself is not deleted. A 400 means an invalid admin_unit_id or admin_id.

[Cisco Duo] Unassign a Duo user group from an administrative unit, removing that group's users from the view of every administrator restricted to the unit. Needs the Duo "Grant administrators - Write" permission. Both ids go in the path and no other parameters are sent. The group and its members are NOT deleted — only this unit's scope changes — but administrators who relied on the unit for access to those users lose it immediately, and if the unit is left with no groups while restrict_by_groups is true its administrators see no users at all. A 400 means an invalid admin_unit_id or group_id.

[Cisco Duo] Unassign an application (integration) from an administrative unit, removing it from the view of every administrator restricted to that unit. Needs the Duo "Grant administrators - Write" permission. Both the unit id and the integration_key go in the path and no other parameters are sent. The application is NOT deleted and keeps authenticating users normally — only this unit's scope changes — but administrators who relied on the unit to manage it lose that access immediately, and if the unit is left with no integrations while restrict_by_integrations is true its administrators see no applications at all. A 400 means an invalid admin_unit_id or integration_key.

[Cisco Duo] Retrieve account activity events — the audit trail of changes made in the Duo Admin Panel and through the Admin API. Requires the Duo application's log-reading permission. TIME BOUNDS ARE REQUIRED AND ARE 13-DIGIT MILLISECOND timestamps; mintime must be strictly less than maxtime and the documented maximum range is 180 days. To page, pass the nextOffset value from the previous response's metadata back verbatim — it is an opaque string cursor, not a number.

[Cisco Duo] Retrieve the administrator-action audit log — what Duo administrators did and when. Requires the Duo application's log-reading permission. This is Duo's older log endpoint and has a much smaller parameter surface than the authentication, activity and telephony logs: it takes only an optional lower time bound, IN SECONDS rather than milliseconds, and offers no page size, cursor or sort. For a richer audit trail of administrative changes, use duo_get_activity_logs instead.

[Cisco Duo] Retrieve authentication events — who authenticated, from where, with which factor, and whether it succeeded. Covers the last 180 days. Requires the Duo application's log-reading permission. TIME BOUNDS ARE REQUIRED AND ARE 13-DIGIT MILLISECOND timestamps (not seconds): mintime must be strictly less than maxtime. There is an intentional delay of about two minutes before new events appear, and Duo recommends requesting logs no more than once a minute — a query for the last few seconds legitimately returns nothing. To page, pass the nextOffset value from the previous response's metadata back VERBATIM; it is an opaque cursor of the form "1547486297000,5bea1c1e-612c-4f1d-b310-75fd31385b15", not a number. Absence of a next offset in the metadata means there are no further pages. The filter parameters accept comma-delimited lists, and multiple values in one filter are combined with OR.

[Cisco Duo] Retrieve offline-access enrolment and activation events for Duo Authentication for Windows Logon — which endpoints enrolled for offline access and when they used it. Requires the Duo application's log-reading permission. Like the administrator log this is Duo's older endpoint shape: an optional lower time bound IN SECONDS, with no page size, cursor or sort.

[Cisco Duo] Retrieve telephony events — the SMS messages and voice calls Duo has sent, including the telephony credits each consumed. Useful for investigating credit consumption. Requires the Duo application's log-reading permission. TIME BOUNDS ARE REQUIRED AND ARE 13-DIGIT MILLISECOND timestamps. To page, pass the nextOffset value from the previous response's metadata back verbatim — it is an opaque string cursor, not a number.

[Cisco Duo] Remove the legacy account logo from the Duo prompt and from future Duo Mobile activations. DEPRECATED BY DUO — superseded by custom branding. Already-enrolled devices must be re-activated before the logo disappears from them. This call is idempotent: Duo returns success whether or not a logo was present, which does NOT make it non-destructive — the previous logo is gone and must be re-uploaded to restore it. Requires the Duo application's settings permission.

[Cisco Duo] Download the legacy account logo shown in the Duo prompt and Duo Mobile. DEPRECATED BY DUO — this endpoint is superseded by custom branding and will stop working in a future Duo update; use duo_get_live_branding instead. Duo returns PNG image data rather than JSON, so the image is uploaded to secure storage and this tool returns a short-lived read-only download URL along with the content type, suggested filename, size in bytes and expiry. A 404 means no legacy logo is configured. Requires the Duo application's settings permission.

[Cisco Duo] Retrieve the account's global Duo settings — the same values shown on the Settings page of the Duo Admin Panel. Covers the caller ID used for voice calls, passcode and Duo Mobile behavior, SMS message text and expiry, lockout thresholds and durations, inactive-user and pending-deletion windows, administrator password policy, log retention, telephony cost limits, timezone and language, and the various notification toggles. Requires the Duo application's settings permission. Call this before duo_modify_settings so you can see the current values and change only what you intend to.

[Cisco Duo] Replace the legacy account logo. DEPRECATED BY DUO — Duo documents that updates to this endpoint HAVE NO EFFECT and that it will stop working in a future update; use duo_modify_draft_branding followed by duo_publish_draft_branding instead. If you do call it, the image must be base-64 encoded PNG data no larger than 500 by 500 pixels and 200 KB, and Duo recommends 304 by 304 with a transparent background. Note that already-enrolled devices must be re-activated before they pick up a changed logo. Requires the Duo application's settings permission.

[Cisco Duo] Change global Duo settings for the whole account. THIS AFFECTS EVERY USER AND EVERY PROTECTED APPLICATION — settings such as lockout thresholds, passcode and push availability, and inactive-user expiration change how and whether people can authenticate. Read duo_get_settings first and send only the fields you intend to change; any field you omit keeps its current value. Requires the Duo application's settings permission. Duo enforces bounds on several fields server-side, notably log_retention_days (1 to 365) and minimum_password_length (12 to 100), and rejects out-of-range values. Field names are the same ones duo_get_settings returns, for example caller_id, sms_message, sms_expiration, lockout_threshold, lockout_expire_duration, inactive_user_expiration, pending_deletion_days, log_retention_days, minimum_password_length, push_enabled, sms_enabled, voice_enabled, mobile_otp_enabled, timezone and language.

[Cisco Duo] Let one Duo user preview the DRAFT custom branding. That user will see the draft in their Duo prompt while everyone else continues to see the live branding — this is how you check a branding change against a real login before publishing it. Requires the Duo application's settings permission.

[Cisco Duo] Retrieve the custom help text and help links shown to end users in the Duo prompt — typically how to reach your help desk. Requires the Duo application's settings permission.

[Cisco Duo] Retrieve the staged DRAFT custom branding along with the users nominated to preview it. The draft is invisible to everyone except those preview users until it is published. Requires the Duo application's settings permission.

[Cisco Duo] Retrieve the custom branding currently LIVE for end users — the logo, background image, page background color, card accent color, the "powered by Duo" setting, and any custom SSO username label. Requires the Duo application's settings permission. Custom branding supersedes the older account-logo endpoints.

[Cisco Duo] Change the custom help text and help links shown to end users in the Duo prompt. This is LIVE end-user-facing text and replaces what is there now, so read duo_get_custom_messaging first if you may need to restore it. IMPORTANT: locale is REQUIRED whenever you supply help text, because the text is stored per language; omitting it with help text present is rejected. Requires the Duo application's settings permission.

[Cisco Duo] Change the DRAFT custom branding. Nothing any ordinary end user sees changes until the draft is published with duo_publish_draft_branding — this is the safe way to stage a branding change. Only the fields you supply are changed. You can also set the draft's preview users here, or manage them individually with duo_add_draft_branding_user and duo_remove_draft_branding_user. Requires the Duo application's settings permission.