Resources/The Agent API Atlas/Security/Duo

Everything an AI agent can do with the Duo API.

A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.

Endpoints47

API versionv1

Last updated23 June 2026

Orientation

How the Duo Admin API works.

The Duo API is how an app or AI agent manages a Cisco Duo account: listing and editing users, enrolling phones and hardware tokens, generating bypass codes, managing administrators and the applications Duo protects, and reading authentication and administrator logs. Access is granted through an integration key and a secret key that sign each request, and the permissions set on that integration, like read-only or settings, are the only boundary on what it can reach. Duo does not push events, so new activity is read by polling the log endpoints.

47Endpoints

9Capability groups

22Read

25Write

6Permissions

Authentication

The Admin API uses an integration key, a secret key, and an account-specific API hostname. Every request is signed with HMAC-SHA1 over a canonical string of the date, HTTP method, host, path, and sorted parameters, using the secret key, and the signature is sent through HTTP Basic authentication with the integration key as the username. The Date header must be present, in RFC 2822 format, and within Duo's clock tolerance. There are no OAuth scopes and no bearer tokens.

Permissions

Capability is decided when the Admin API integration is created, not per call. The integration is given coarse permission grants, like Grant read resource and Grant write resource for users, phones, tokens, groups, and endpoints; Grant applications for the applications it protects; Grant administrators, set to read or write, for administrator accounts; Grant read log for the logs; and Grant settings for account settings. There is no finer scoping than these grants, so a single key carries the same access to every object of a type it can reach. A least-privilege setup uses a read-only integration, or a separate integration per task.

Versioning

The Admin API is versioned by a number in the path, mostly v1. Several read endpoints have a v2 with a different request and response shape, including the authentication, telephony, and activity logs, which require a mintime and maxtime window in millisecond timestamps, and the single-group and group-members reads. A separate v1 legacy reference documents the earlier shapes. The version is chosen by the path the call uses.

Data model

The API is resource-oriented JSON over HTTPS at the account's API hostname, with every response wrapped in an envelope carrying stat, either OK with a response object or FAIL with a code and message. Core resources are users, phones, hardware tokens, bypass codes, groups, integrations (applications), administrators, and endpoints, plus read-only logs and account settings. Duo does not push events, so new activity is read by polling the log endpoints.

Connect & authenticate

Connection & authentication methods.

How an app or AI agent connects to Duo determines what it can reach. The Admin API is the route for managing an account, and it is governed by the integration credentials behind each call and the permissions granted to that integration.

Ways to connect

Admin API

The Admin API answers at the account's own API hostname, like api-XXXXXXXX.duosecurity.com. Each request is signed with HMAC-SHA1 over the date, method, path, and parameters, using the integration's secret key, and the signature is sent through HTTP Basic authentication.

Best forConnecting an app or AI agent to manage a Duo account.

Governed byThe integration key and secret key, and the permissions granted to that integration.

Docs ↗

Auth API

The Auth API is a separate Duo API for performing second-factor authentication itself, like sending a Duo Push or verifying a passcode. It does not manage the account and uses its own integration credentials.

Best forAdding Duo two-factor checks to an application's own login.

Governed byA separate Auth API integration key and secret key.

Docs ↗

Accounts API

The Accounts API is a separate Duo API, used mainly by managed service providers, to create, delete, and manage child Duo accounts under a parent account. Each child account is then managed through its own Admin API integration.

Best forProvisioning and managing multiple Duo customer accounts.

Governed byA parent-account Accounts API integration key and secret key.

Docs ↗

Authentication

Admin API integration credentials

An Admin API integration has an integration key, a secret key, and an API hostname. Every request is signed with HMAC-SHA1 over a canonical string of the date, method, host, path, and parameters, using the secret key, and the result is sent through HTTP Basic authentication. There are no OAuth scopes; the integration's granted permissions are the boundary.

TokenIntegration key and secret key (HMAC-SHA1 signed)

Best forServer-side access to manage a Duo account

Docs ↗

Integration permissions

Capability is set when the integration is created, through permission grants like Grant read resource, Grant write resource, Grant applications, Grant administrators, Grant settings, and Grant read log. These grants are coarse, covering whole resource types rather than a single object, and they are the only boundary on what the integration can do.

TokenPermission grants on the integration

Best forLimiting an integration to read-only or to specific areas

Docs ↗

Capability map

What an AI agent can do in Duo.

The Duo Admin API is split into areas an agent can act on, like users, phones, hardware tokens, groups, applications, administrators, and logs. Each area is gated by a permission set on the integration, and some grant access to far more than others.

Users

10 endpoints

List, read, create, modify, and delete users, send enrollment links, and manage the phones, tokens, and groups attached to a user.

Writes here change real user accounts and their enrollment.

View endpoints →

Phones

7 endpoints

List, read, create, modify, and delete phones, and send activation links or SMS passcodes to them.

Writes here change real devices and can send messages to phones.

View endpoints →

Hardware tokens & bypass codes

7 endpoints

List, read, create, resync, and delete hardware tokens, generate bypass codes for a user, and delete bypass codes.

Writes here change second-factor devices and one-time access codes.

View endpoints →

Groups

5 endpoints

List, read, create, and update groups, and read a group's members.

Writes here change group membership and the policies that follow it.

View endpoints →

Applications

5 endpoints

List, read, create, modify, and delete the applications, called integrations, that Duo protects.

Writes here change what Duo protects and the keys those applications use.

View endpoints →

Administrators

5 endpoints

List, read, create, modify, and delete administrators, and send an administrator an activation link to set up their own login.

Writes here change who can administer the Duo account.

View endpoints →

Endpoints

2 endpoints

List and read the endpoints, the laptops and phones, that have accessed Duo-protected applications.

Reads here return device inventory and posture details.

View endpoints →

Logs

4 endpoints

Read the authentication, administrator, telephony, and activity logs that record what happened in the account.

Reads here return detailed records of authentications and admin actions.

View endpoints →

Settings

2 endpoints

Read and update account-level settings, like enrollment, lockout, and messaging defaults.

Writes here change account-wide security defaults.

View endpoints →

Endpoint reference

Every Duo Admin API method.

Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.

Hide deprecated

Method	Endpoint	What it does	Access	Permission	Version
Users List, read, create, modify, and delete users, send enrollment links, and manage the phones, tokens, and groups attached to a user.10
GET	`/admin/v1/users`	Retrieve a paged list of users in the account.	read	`Grant read resource`	Current
Capability is set by the permission granted to the Admin API integration at creation, not by a per-call scope. Reads need Grant read resource. Acts onuser Permission (capability)`Grant read resource` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
GET	`/admin/v1/users/[user_id]`	Retrieve a single user by ID.	read	`Grant read resource`	Current
Reads need Grant read resource on the integration. Acts onuser Permission (capability)`Grant read resource` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/admin/v1/users`	Create a single user.	write	`Grant write resource`	Current
Writes need Grant write resource on the integration. Acts onuser Permission (capability)`Grant write resource` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/admin/v1/users/[user_id]`	Modify a user's attributes, like status or username.	write	`Grant write resource`	Current
Setting a user's status to disabled or bypass changes whether and how they pass second-factor checks. Writes need Grant write resource. Acts onuser Permission (capability)`Grant write resource` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
DELETE	`/admin/v1/users/[user_id]`	Permanently delete a user.	write	`Grant write resource`	Current
Deletion is permanent. Writes need Grant write resource. Acts onuser Permission (capability)`Grant write resource` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/admin/v1/users/enroll`	Create a user if needed and email them an enrollment link with an expiring code.	write	`Grant write resource`	Current
Sends an email to the address given. Writes need Grant write resource. Acts onuser Permission (capability)`Grant write resource` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/admin/v1/users/bulk_create`	Create up to 100 users in one request.	write	`Grant write resource`	Current
Held to 50 calls per minute. Writes need Grant write resource. Acts onuser Permission (capability)`Grant write resource` VersionAvailable since the API’s base version Webhook eventNone Rate limit50 calls per minute SourceOfficial documentation ↗
GET	`/admin/v1/users/[user_id]/phones`	List the phones associated with a user.	read	`Grant read resource`	Current
Reads need Grant read resource on the integration. Acts onuser phone Permission (capability)`Grant read resource` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/admin/v1/users/[user_id]/phones`	Associate an existing phone with a user.	write	`Grant write resource`	Current
Writes need Grant write resource on the integration. Acts onuser phone Permission (capability)`Grant write resource` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/admin/v1/users/[user_id]/bypass_codes`	Generate bypass codes for a user that let them sign in without a second factor.	write	`Grant write resource`	Current
Bypass codes let a person past second-factor verification, so this is a sensitive write. Writes need Grant write resource. Acts onbypass code Permission (capability)`Grant write resource` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
Phones List, read, create, modify, and delete phones, and send activation links or SMS passcodes to them.7
GET	`/admin/v1/phones`	Retrieve a paged list of phones in the account.	read	`Grant read resource`	Current
Reads need Grant read resource on the integration. Acts onphone Permission (capability)`Grant read resource` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
GET	`/admin/v1/phones/[phone_id]`	Retrieve a single phone by ID.	read	`Grant read resource`	Current
Reads need Grant read resource on the integration. Acts onphone Permission (capability)`Grant read resource` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/admin/v1/phones`	Create a new phone.	write	`Grant write resource`	Current
Writes need Grant write resource on the integration. Acts onphone Permission (capability)`Grant write resource` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/admin/v1/phones/[phone_id]`	Modify a phone's attributes.	write	`Grant write resource`	Current
Writes need Grant write resource on the integration. Acts onphone Permission (capability)`Grant write resource` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
DELETE	`/admin/v1/phones/[phone_id]`	Delete a phone.	write	`Grant write resource`	Current
Writes need Grant write resource on the integration. Acts onphone Permission (capability)`Grant write resource` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/admin/v1/phones/[phone_id]/send_sms_passcodes`	Send a batch of passcodes to a phone by SMS.	write	`Grant write resource`	Current
Sends a text message and may incur telephony cost. Writes need Grant write resource. Acts onphone Permission (capability)`Grant write resource` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/admin/v1/phones/[phone_id]/activation_url`	Create an activation link that enrolls Duo Mobile on a phone.	write	`Grant write resource`	Current
An activation link, if intercepted, can bind Duo Mobile to an attacker's device. Writes need Grant write resource. Acts onphone Permission (capability)`Grant write resource` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
Hardware tokens & bypass codes List, read, create, resync, and delete hardware tokens, generate bypass codes for a user, and delete bypass codes.7
GET	`/admin/v1/tokens`	Retrieve a paged list of hardware tokens.	read	`Grant read resource`	Current
Reads need Grant read resource on the integration. Acts onhardware token Permission (capability)`Grant read resource` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
GET	`/admin/v1/tokens/[token_id]`	Retrieve a single hardware token by ID.	read	`Grant read resource`	Current
Reads need Grant read resource on the integration. Acts onhardware token Permission (capability)`Grant read resource` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/admin/v1/tokens`	Create a hardware token, such as a TOTP or YubiKey token.	write	`Grant write resource`	Current
Writes need Grant write resource on the integration. Acts onhardware token Permission (capability)`Grant write resource` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/admin/v1/tokens/[token_id]/resync`	Resync a hardware token's counter using consecutive codes.	write	`Grant write resource`	Current
Writes need Grant write resource on the integration. Acts onhardware token Permission (capability)`Grant write resource` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
DELETE	`/admin/v1/tokens/[token_id]`	Delete a hardware token.	write	`Grant write resource`	Current
Writes need Grant write resource on the integration. Acts onhardware token Permission (capability)`Grant write resource` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
GET	`/admin/v1/bypass_codes`	Retrieve metadata for bypass codes across the account.	read	`Grant read resource`	Current
Returns metadata, not the code values. Reads need Grant read resource. Acts onbypass code Permission (capability)`Grant read resource` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
DELETE	`/admin/v1/bypass_codes/[bypass_code_id]`	Delete a bypass code by ID.	write	`Grant write resource`	Current
Writes need Grant write resource on the integration. Acts onbypass code Permission (capability)`Grant write resource` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
Groups List, read, create, and update groups, and read a group's members.5
GET	`/admin/v1/groups`	Retrieve a paged list of groups.	read	`Grant read resource`	Current
Reads need Grant read resource on the integration. Acts ongroup Permission (capability)`Grant read resource` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/admin/v1/groups`	Create a group.	write	`Grant write resource`	Current
Writes need Grant write resource on the integration. Acts ongroup Permission (capability)`Grant write resource` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
GET	`/admin/v2/groups/[group_id]`	Retrieve a single group's details.	read	`Grant read resource`	Current
This read endpoint is served at v2. Reads need Grant read resource. Acts ongroup Permission (capability)`Grant read resource` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
GET	`/admin/v2/groups/[group_id]/users`	Retrieve the members of a group.	read	`Grant read resource`	Current
Served at v2 with paging. Reads need Grant read resource. Acts ongroup Permission (capability)`Grant read resource` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/admin/v1/groups/[group_id]`	Update a group's attributes.	write	`Grant write resource`	Current
Writes need Grant write resource on the integration. Acts ongroup Permission (capability)`Grant write resource` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
Applications List, read, create, modify, and delete the applications, called integrations, that Duo protects.5
GET	`/admin/v1/integrations`	Retrieve a paged list of applications, called integrations.	read	`Grant applications`	Current
Applications use the separate Grant applications permission, not Grant read or write resource. Acts onapplication Permission (capability)`Grant applications` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
GET	`/admin/v1/integrations/[integration_key]`	Retrieve a single application by its integration key.	read	`Grant applications`	Current
The response includes the application's own keys. Needs Grant applications. Acts onapplication Permission (capability)`Grant applications` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/admin/v1/integrations`	Create an application, called an integration, for Duo to protect.	write	`Grant applications`	Current
Creating an application can set its own Admin API permissions, governed by Grant applications. Acts onapplication Permission (capability)`Grant applications` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/admin/v1/integrations/[integration_key]`	Modify an application's settings.	write	`Grant applications`	Current
Needs Grant applications on the integration. Acts onapplication Permission (capability)`Grant applications` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
DELETE	`/admin/v1/integrations/[integration_key]`	Delete an application.	write	`Grant applications`	Current
Deleting an application stops Duo protecting it. Needs Grant applications. Acts onapplication Permission (capability)`Grant applications` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
Administrators List, read, create, modify, and delete administrators, and send an administrator an activation link to set up their own login.5
GET	`/admin/v1/admins`	Retrieve a paged list of administrators.	read	`Grant administrators`	Current
Administrators use the separate Grant administrators permission, set to read or write. Acts onadministrator Permission (capability)`Grant administrators` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
GET	`/admin/v1/admins/[admin_id]`	Retrieve a single administrator by ID.	read	`Grant administrators`	Current
Needs Grant administrators read. Acts onadministrator Permission (capability)`Grant administrators` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/admin/v1/admins`	Create an administrator.	write	`Grant administrators`	Current
Creating an administrator grants a person access to the Duo Admin Panel. Needs Grant administrators write. Acts onadministrator Permission (capability)`Grant administrators` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/admin/v1/admins/[admin_id]`	Modify an administrator's attributes, like role.	write	`Grant administrators`	Current
Changing an administrator's role changes what they can do. Needs Grant administrators write. Acts onadministrator Permission (capability)`Grant administrators` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
DELETE	`/admin/v1/admins/[admin_id]`	Delete an administrator.	write	`Grant administrators`	Current
Needs Grant administrators write. Acts onadministrator Permission (capability)`Grant administrators` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
Endpoints List and read the endpoints, the laptops and phones, that have accessed Duo-protected applications.2
GET	`/admin/v1/endpoints`	Retrieve a paged list of endpoints, the devices that have accessed Duo-protected applications.	read	`Grant read resource`	Current
Reads need Grant read resource on the integration. Acts onendpoint Permission (capability)`Grant read resource` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
GET	`/admin/v1/endpoints/[endpoint_id]`	Retrieve a single endpoint's details, including posture information.	read	`Grant read resource`	Current
Reads need Grant read resource on the integration. Acts onendpoint Permission (capability)`Grant read resource` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
Logs Read the authentication, administrator, telephony, and activity logs that record what happened in the account.4
GET	`/admin/v2/logs/authentication`	Read authentication attempt records, filtered by a required time window.	read	`Grant read log`	Current
Served at v2, requiring mintime and maxtime as 13-digit millisecond timestamps. New records appear after about a two minute delay. Needs Grant read log. Acts onauthentication log Permission (capability)`Grant read log` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
GET	`/admin/v1/logs/administrator`	Read the history of administrator actions in the account.	read	`Grant read log`	Current
Served at v1. Needs Grant read log. Acts onadministrator log Permission (capability)`Grant read log` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
GET	`/admin/v2/logs/telephony`	Read telephony events, like SMS and phone-call usage.	read	`Grant read log`	Current
Served at v2 with a required time window. Needs Grant read log. Acts ontelephony log Permission (capability)`Grant read log` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
GET	`/admin/v2/logs/activity`	Read the activity log, a unified record of changes and events in the account.	read	`Grant read log`	Current
Served at v2 with a required time window. Needs Grant read log. Acts onactivity log Permission (capability)`Grant read log` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
Settings Read and update account-level settings, like enrollment, lockout, and messaging defaults.2
GET	`/admin/v1/settings`	Retrieve account-level settings.	read	`Grant settings`	Current
Settings use their own Grant settings permission, separate from resource and log grants. Acts onsettings Permission (capability)`Grant settings` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/admin/v1/settings`	Update account-level settings, like enrollment and lockout defaults.	write	`Grant settings`	Current
Changes account-wide security defaults. Needs Grant settings. Acts onsettings Permission (capability)`Grant settings` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗

No endpoints match those filters.

Webhooks

Webhook events.

Duo does not push events to a receiver. New activity, like an authentication attempt or an administrator action, is read by polling the relevant log endpoint on a schedule.

Event	What it signals	Triggered by

No events match that search.

Rate limits & pagination

Rate limits, pagination & request size.

Duo limits how fast an app or AI agent can call, by request-rate thresholds measured per IP address and per account, and slows requests as they approach the threshold before rejecting them.

Request rate

Duo enforces request-rate limits through three mechanisms evaluated in turn: per IP address across all customers on a deployment, per integration plus IP address for a single customer, and per integration across all IP addresses for that customer. As the request count nears a threshold, Duo delays requests to slow the client down, and at the threshold it rejects them with HTTP 429. Specific bulk endpoints carry their own published limit, like bulk user creation at 50 calls per minute. The separate Auth API also limits authentications per user per minute, at 10 on the free edition and 30 on paid editions.

Pagination

List endpoints use offset paging through the limit and offset parameters, where limit sets the page size and offset sets the starting position, defaulting to 0. The response metadata returns total_objects, next_offset, and prev_offset, and a client keeps requesting while next_offset is present. The v2 log endpoints take a required mintime and maxtime time window in millisecond timestamps and page within it.

Request size

Requests are form-encoded and responses are JSON wrapped in a stat envelope. Bulk user creation accepts up to 100 users per request, and the general bulk endpoint runs up to 50 operations in one call. Individual list endpoints set their own maximum page size, commonly in the hundreds.

Errors

Status codes & error handling.

The status codes an agent should handle, and what to do about each.

Status	Code	Meaning	What to do
400	`Invalid request parameters`	A required parameter is missing or a parameter value is invalid.	Check the documented parameters for the method, then correct and resend the request.
401	`Missing or invalid credentials`	The Authorization or Date header is missing, or the HMAC-SHA1 signature does not match.	Confirm the integration key, secret key, and signing string, and that the Date header is in RFC 2822 format and within clock tolerance.
403	`Access forbidden`	The integration lacks the permission for this call, or the wrong type of integration key is being used, or an IP restriction blocked the request.	Grant the required permission on the integration, use an Admin API key, or call from an allowed IP address.
404	`Resource not found`	The path or the referenced object, like a user or phone ID, does not exist.	Confirm the path and the object ID before retrying.
405	`Method not allowed`	The HTTP method is not supported for this endpoint.	Use the documented method for the endpoint, such as GET for a list and POST for a change.
429	`Too many requests`	A rate limit was exceeded. Duo slows requests as they approach the threshold and rejects them with 429 once it is reached.	Wait and retry with exponential backoff. The response body carries stat FAIL with a code and message.

Versioning & freshness

Version history.

Duo versions the Admin API by a number in the path. Most endpoints answer at v1, and several read endpoints, including the authentication, telephony, and activity logs, have a v2 with a different request and response shape.

Version history

What changed, and when

Latest versionv1

v1Current version

Admin API versioned by path, with v2 read endpoints

The Duo Admin API is versioned by a number in the path. Most endpoints answer at v1, and Duo has added v2 versions for several read endpoints with a changed request and response shape, including the authentication, telephony, and activity logs and the single-group and group-members reads. The v2 log endpoints require a mintime and maxtime window in millisecond timestamps. A separate legacy reference documents the original v1 log shapes.

What changed

Authentication, telephony, and activity logs read at v2 with a required mintime and maxtime millisecond window
Single-group and group-members reads served at v2 with paging
Most management endpoints remain at v1

Earlier

Legacy v1 log shapes

An earlier form of the v1 logs returned a flat list without the v2 time-window and paging model. Duo keeps a separate legacy Admin API reference documenting these older endpoint shapes for integrations that have not yet moved to v2.

What changed

Original v1 authentication and telephony logs returned a simple list
Documented in a separate legacy Admin API reference

An integration calls the version in the path it needs, and moves a read endpoint to v2 when ready.

Duo Admin API reference ↗

Questions

Duo Admin API, answered.

How does an integration authenticate to the Duo Admin API?+

Each request is signed rather than carrying a bearer token. The client builds a canonical string from the request's date, HTTP method, API hostname, path, and alphabetically sorted parameters, then computes an HMAC-SHA1 of that string using the integration's secret key. The integration key and that signature are sent as the username and password in an HTTP Basic Authorization header, alongside a Date header in RFC 2822 format. A wrong signature, a missing Date header, or a clock skew beyond Duo's tolerance returns a 401.

How do permissions work, and how fine-grained are they?+

Permissions are set on the Admin API integration when it is created, not requested per call. The grants are coarse: Grant read resource and Grant write resource cover users, phones, tokens, groups, and endpoints together; Grant applications covers the protected applications; Grant administrators, read or write, covers admin accounts; Grant read log covers the logs; and Grant settings covers account settings. There is no per-object scoping, so a key with Grant write resource can change any user or phone in the account. The way to limit an agent is a read-only integration, or a separate integration scoped to one task, which is exactly the boundary Bollard adds in front.

Does Duo support webhooks, or does it have to be polled?+

The Admin API does not push events to a receiver. New activity, like authentication attempts and administrator actions, is read by polling the relevant log endpoint. The authentication, telephony, and activity logs are read at v2 with a required mintime and maxtime window in millisecond timestamps, and there is an intentional delay of about two minutes before the newest authentications appear, so a query for the last two minutes can come back empty.

What are the rate limits, and what happens when one is hit?+

Duo applies request-rate limits per IP address, per integration plus IP address, and per integration across all IP addresses. As requests approach a threshold Duo slows them down, and at the threshold it returns HTTP 429 with a stat FAIL body. Some bulk endpoints publish their own limit, such as bulk user creation at 50 calls per minute. The fix is to back off and retry, ideally with exponential backoff. The separate Auth API limits authentications per user per minute, at 10 on the free edition and 30 on paid editions.

What is the difference between the Admin API, the Auth API, and the Accounts API?+

They are three separate Duo APIs with their own credentials. The Admin API manages an account: its users, devices, applications, administrators, logs, and settings. The Auth API performs second-factor authentication itself, like sending a Duo Push or checking a passcode, and is what an application calls during a login. The Accounts API, used mainly by managed service providers, creates and manages child accounts under a parent account, each then run through its own Admin API integration.

Does Duo offer an official MCP server for the Admin API?+

Not for calling the Admin API. Duo's Model Context Protocol work is on the identity side: Duo Single Sign-On can add two-factor authentication in front of MCP clients, and Duo Agentic Identity describes an MCP gateway for controlling AI agents. Neither exposes the Admin API as MCP tools, so an agent that needs to manage a Duo account calls the signed Admin API directly. That is the gap Bollard fills, by sitting in front of the Admin API and governing each call.

What is Bollard AI?

Control what every AI agent can do in Duo.

Bollard AI sits between a team's AI agents and Duo. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.

Set read, write, or full access per agent, never a shared Duo key.
Denied by default, so an agent reaches only what has been explicitly allowed.
Every call recorded in plain English: who, what, where, and the decision.

Control Duo access in Bollard Browse all APIs →

Duo

Helpdesk Agent

Read users and devices ResourceOffReadFull use

Generate bypass codes ActionOffReadFull use

Read authentication logs ResourceOffReadFull use

Manage admins ResourceOffReadFull use

Per-agent access, set in Bollard AI, not in Duo

How the Duo Admin API works.

Connection & authentication methods.

Admin API

Auth API

Accounts API

Admin API integration credentials

Integration permissions

What an AI agent can do in Duo.

Users

Phones

Hardware tokens & bypass codes

Groups

Applications

Administrators

Endpoints

Logs

Settings

Every Duo Admin API method.

Users

Phones

Hardware tokens & bypass codes

Groups

Applications

Administrators

Endpoints

Logs

Settings

Webhook events.

Rate limits, pagination & request size.

Request rate

Pagination

Request size

Status codes & error handling.

Version history.

What changed, and when

Duo Admin API, answered.

More security API guides for agents

WorkOS

Clerk

CrowdStrike

JumpCloud

Okta

Microsoft Entra ID

Control what every AI agent can do in Duo.