Duo Admin API

Overview

Duo Admin API is automatically available to paying Duo Premier, Duo Advantage, and Duo Essentials plan customers and new customers with an Advantage or Premier trial. Learn how to sign up for a Duo account and receive a free 30-day Duo Advantage trial.

The Admin API lets developers integrate with Duo Security's platform at a low level. The API has methods for creating, retrieving, updating, and deleting the core objects in Duo's system: users, phones, hardware tokens, admins, and integrations.

Developers can write applications that programmatically read their Duo account's authentication logs, administrator logs, and telephony logs; read or update account settings; and retrieve reports and other information.

Review the API Details to see how to construct your first API request.

About the Admin API

Documented properties will not be removed within a stable version of the API. Once a given API endpoint is documented to return a given property, a property with that name will always appear (although certain properties may only appear under certain conditions, like if the customer is using a specific edition). When Duo deprecates a property, the API continues to accept that property in requests, although it no longer has any effect.

Properties that enumerate choices may gain new values at any time, e.g. the device platform value could return new device platforms that did not previously exist. Duo may cease to return legacy values for properties as well. Duo will update our API documentation with changes to property values in a timely fashion, adding new property values or indicating changes to existing property values.

New, undocumented properties may also appear at any time. For instance, Duo may make available a beta feature involving extra information returned by an API endpoint. Until the property is documented here its format may change or it may even be entirely removed from our API.

We have started implementing v2 and v3 handlers for endpoints. In these cases, the API v1 and v2 handlers remain supported, but will be limited or deprecated in the future. We encourage use of the most current endpoints where available and recommend migrating existing API implementations to the v2 and v3 handlers.

Please note that all Unix timestamps are in seconds, except where noted.

First Steps

Role required: Owner

1. Sign up for a Duo account if you aren't already a customer. Your free 30-day Duo Advantage trial includes Admin API access.

2. Log in to the Duo Admin Panel and navigate to Applications → Application Catalog.

3. Locate the entry for Admin API in the catalog. Click the + Add button to create the application, and get your integration key, secret key, and API hostname. You'll need this information to complete your setup. See Protecting Applications for more information about protecting applications with Duo and additional application options.

   Treat your secret key like a password

   The security of your Duo application is tied to the security of your secret key (skey). Secure it as you would any sensitive credential. Don't share it with unauthorized individuals or email it to anyone under any circumstances!

4. Determine the permissions you want to grant to this Admin API application. Refer to the API endpoint descriptions throughout this document for information about required permissions for operations.

   Permission	Details
   Grant administrators - Read	The Admin API application can read information about Duo administrators and administrative units.
   Grant administrators - Write	The Admin API application can read, add, modify, and delete information about Duo administrators and administrative units.
   Grant read information	The Admin API application can read information about the Duo customer account's utilization.
   Grant applications	The Admin API application can add, modify, and delete applications (referred to as "integrations" in the API), including permissions on itself or other Admin API applications.
   Grant settings	The Admin API application can read and change global Duo account settings.
   Grant read log	The Admin API application can read authentication, offline access, telephony, and administrator action log information.
   Grant resource - Read	The Admin API application can read information about resource objects such as end users, policies, and devices.
   Grant resource - Write	The Admin API application can create, update, and delete resource objects such as end users, policies, and devices.
   Grant set Admin API permissions	The Admin API application can add or remove the permissions listed above via API for other Admin API applications. When this permission is not granted, permissions for an Admin API application must be set from the Duo Admin Panel.

5. Optionally specify which IP addresses or ranges are allowed to use this Admin API application in Networks for API Access. If you do not specify any IP addresses or ranges, this Admin API application may be accessed from any network.

   The Admin API performs the IP check after verifying the authentication signature in a request. If you restrict the allowed networks for API access and see logged events for blocked Admin API requests from unrecognized IP addresses, this may indicate compromise of your Admin API application's secret key.

API Clients

Duo Security has demonstration clients available on GitHub to call the Duo API methods.

• Python (duo_client_python)
• Java (duo_client_java)
• C# (duo_api_csharp)
• Go (duo_api_golang)
• Node (duo_api_nodejs)
• Ruby (duo_api_ruby)
• Perl (duo_api_perl)
• PHP (duo_api_php)

API Details

Base URL

All API methods use your API hostname, https://api-XXXXXXXX.duosecurity.com. Obtain this value from the Duo Admin Panel and use it exactly as shown there.

Methods always use HTTPS. Unsecured HTTP is not supported.

Request Format

All requests must have "Authorization" and "Date" headers.

If the request method is GET or DELETE, URL-encode parameters and send them in the URL query string like this: /admin/v1/users?realname=First%20Last&username=root. They still go on a separate line when creating the string to sign for an Authorization header.

Send parameters for POST requests in the body as URL-encoded key-value pairs (the same request format used by browsers to submit form data). The header "Content-Type: application/x-www-form-urlencoded" must also be present.

When URL-encoding, all bytes except ASCII letters, digits, underscore ("_"), period ("."), tilde ("~"), and hyphen ("-") are replaced by a percent sign ("%") followed by two hexadecimal digits containing the value of the byte. For example, a space is replaced with "%20" and an at-sign ("@") becomes "%40". Use only upper-case A through F for hexadecimal digits.

A request with parameters, as a complete URL, would look like this: https://api-XXXXXXXX.duosecurity.com/admin/v1/users?realname=First%20Last&username=root.

Response Format

Responses are formatted as a JSON object with a top-level stat key.

Successful responses will have a stat value of "OK" and a response key. The response will either be a single object or a sequence of other JSON types, depending on which endpoint is called.

{
  "stat": "OK",
  "response": {
    "key": "value"
  }
}

Values are returned as strings unless otherwise documented.

Unsuccessful responses will have a stat value of "FAIL", an integer code, and a message key that further describes the failure. A message_detail key may be present if additional information is available (like the specific parameter that caused the error).

{
  "stat": "FAIL",
  "code": 40002,
  "message": "Invalid request parameters",
  "message_detail": "username"
}

The HTTP response code will be the first three digits of the more specific code found inside the JSON object. Each endpoint's documentation lists HTTP response codes it can return. Additionally, all API endpoints that require a signed request can return the following HTTP response codes:

Response Paging

Some API endpoints return a paged list of results on GET, up to the API endpoint's limit, or maximum results per page.

A successful response when the total results exceed the endpoint's default page size will include a metadata section with information about the total number of objects found and the results returned in the paged response. If the request returns no paging metadata, then either the endpoint does not support paged results or the total results do not exceed one page.

Specifying incorrect paging parameters results in a 400 invalid parameters response.

Use the metadata information returned to change the paging parameters for your request.

To retrieve the full set of results for a request with paged results, repeat the call, specifying the offset parameter value, until there are no more results (indicated by the absence of next_offset).

Paging Metadata Examples:

The metadata response will look like these examples except where noted for an individual API endpoint.

This metadata information indicates that there are 951 total objects returned by that endpoint, and no offset or limit was specified so the response set defaulted to the first 100 objects:

{
    "metadata": {
        "next_offset": 100,
        "prev_offset": 0,
        "total_objects": 951
    }

This metadata information indicates that the request specified offset=500 limit=200, so the response set was objects 500-699:

{
    "metadata": {
        "next_offset": 700,
        "prev_offset": 300,
        "total_objects": 11318
    }

This metadata information indicates that there are 2342 total objects, and the request specified offset=2300 and used that endpoint's default limit of 100, so the response set was the end of the list (objects 2300-2342):

{
    "metadata": {
        "prev_offset": 2200,
        "total_objects": 2342
    }

Authentication

The API uses HTTP Basic Authentication to authenticate requests. Use your Duo application's integration key as the HTTP Username.

Generate the HTTP Password as an HMAC signature of the request. This will be different for each request and must be re-generated each time.

To construct the signature, first build an ASCII string from your request, using the following components:

Then concatenate these components with (line feed) newlines. For example:

Tue, 21 Aug 2012 17:29:18 -0000
POST
api-xxxxxxxx.duosecurity.com
/admin/v1/users
realname=First%20Last&username=root

GET requests also use this five-line format:

Tue, 21 Aug 2012 17:29:18 -0000
GET
api-xxxxxxxx.duosecurity.com
/admin/v1/users
username=root

Lastly, compute the HMAC-SHA1 of this canonical representation, using your Duo Admin API application's secret key as the HMAC key. Send this signature as hexadecimal ASCII (i.e. not raw binary data). Use HTTP Basic Authentication for the request, using your integration key as the username and the HMAC-SHA1 signature as the password. Signature validation is case-insensitive, so the signature may be upper or lowercase.

For example, here are the headers for the above POST request to api-XXXXXXXX.duosecurity.com/admin/v1/users, using DIWJ8X6AEYOR5OMC6TQ1 as the integration key and Zh5eGmUq9zpfQnyUIu5OL9iWoMMv5ZNmk3zLJ4Ep as the secret key:

Date: Tue, 21 Aug 2012 17:29:18 -0000
Authorization: Basic RElXSjhYNkFFWU9SNU9NQzZUUTE6YzFlZjQzNzY3YzNlYjNiMzI1OGRiZGRjYTZmOGQwOTQxZTA4NWI5Mg==
Host: api-XXXXXXXX.duosecurity.com
Content-Length: 35
Content-Type: application/x-www-form-urlencoded

Separate HTTP request header lines with CRLF newlines.

The following Python function can be used to construct the "Authorization" and "Date" headers:

import base64, email.utils, hmac, hashlib, urllib
  ​ ​
def sign(method, host, path, params, skey, ikey):
    """
    Return HTTP Basic Authentication ("Authorization" and "Date") headers.
    method, host, path: strings from request
    params: dict of request parameters
    skey: secret key
    ikey: integration key
    """
  ​
    # create canonical string
    now = email.utils.formatdate()
    canon = [now, method.upper(), host.lower(), path]
    args = []
    for key in sorted(params.keys()):
        val = params[key].encode("utf-8")
        args.append(
            '%s=%s' % (urllib.parse.
                       quote(key, '~'), urllib.parse.quote(val, '~')))
    canon.append('&'.join(args))
    canon = '\n'.join(canon)
  ​
    # sign canonical string
    sig = hmac.new(bytes(skey, encoding='utf-8'),
                   bytes(canon, encoding='utf-8'),
                   hashlib.sha1)
    auth = '%s:%s' % (ikey, sig.hexdigest())
  ​
    # return headers
    return {'Date': now, 'Authorization': 'Basic %s' % base64.b64encode(bytes(auth, encoding="utf-8")).decode()}

import base64, email, hmac, hashlib, urllib

def sign(method, host, path, params, skey, ikey):
    """
    Return HTTP Basic Authentication ("Authorization" and "Date") headers.
    method, host, path: strings from request
    params: dict of request parameters
    skey: secret key
    ikey: integration key
    """

    # create canonical string
    now = email.Utils.formatdate()
    canon = [now, method.upper(), host.lower(), path]
    args = []
    for key in sorted(params.keys()):
        val = params[key]
        if isinstance(val, unicode):
            val = val.encode("utf-8")
        args.append(
            '%s=%s' % (urllib.quote(key, '~'), urllib.quote(val, '~')))
    canon.append('&'.join(args))
    canon = '\n'.join(canon)

    # sign canonical string
    sig = hmac.new(skey, canon, hashlib.sha1)
    auth = '%s:%s' % (ikey, sig.hexdigest())

    # return headers
    return {'Date': now, 'Authorization': 'Basic %s' % base64.b64encode(auth)}

If you receive 401 error responses to your API requests, check the following:

• Is the Authorization header correctly formatted? If not, you may receive a 40101 error.
• Does your framework override the Date header? The HTTP Date: header must be exactly the same string as was signed. This could result in a 40103 error.
• Are the Date and time zone used RFC 3339 compliant?? If not, you may get a 40104 or 40105 response.
• Are the parameters lexicographically sorted?
• Did you include a line for parameters when constructing the signature, even if you're not passing in any parameters?
• Are any hex digits lower-case?
• Are the Content-Length and Content-Type parameters correct? If not, your parameters may be ignored or you may receive a 40103 response because your signature considered parameters that the service didn't receive.

Users

Retrieve Users

Returns a paged list of users. To fetch all results, call repeatedly with the offset parameter as long as the result metadata has a next_offset value. If username is not provided, the list will contain all users. If username is provided, the list will either contain a single user (if a match was found) or no users. Requires "Grant resource - Read" API permission.

GET /admin/v1/users

Parameters

Use the paging parameters to change the number of results shown in a response or to retrieve additional results. See Response Paging for details.

Response Codes

Response Format

Example Response

{
  "stat": "OK",
  "response": [
    {
      "alias1": "joe.smith",
      "alias2": "jsmith@example.com",
      "alias3": null,
      "alias4": null,
      "aliases": {
        "alias1": "joe.smith",
        "alias2": "jsmith@example.com"
      },
      "created": 1489612729,
      "custom_attributes": {
          "Company": "Acme",
          "Employee ID": "8675309"
      },
      "desktop_authenticators": [],
      "directory_key": "DABC0DEFGHIJKLMNOPQR",
      "email": "jsmith@example.com",
      "enable_auto_prompt": true,
      "entra_federated_user_id": null,
      "external_id": "1a2345b6-7cd8-9e0f-g1hi-23j45kl6m789",
      "firstname": "Joe",
      "groups": [
        {
        "desc": "People with hardware tokens",
        "group_id": "DGBDKSSH37KSJ373JKSU",
        "mobile_otp_enabled": false,
        "name": "token_users",
        "push_enabled": false,
        "sms_enabled": false,
        "status": "Active",
        "voice_enabled": false
        }
      ],
      "is_enrolled": true,
      "last_directory_sync": 1508789163,
      "last_login": 1343921403,
      "lastname": "Smith",
      "lockout_reason": null,
      "notes": "",
      "phones": [
        {
        "activated": true,
        "app_version": "4.87.0",
        "capabilities": [
          "auto",
          "push",
          "sms",
          "phone",
          "mobile_otp"
        ],
        "creation_date": "",
        "encrypted": "Encrypted",
        "extension": "",
        "fingerprint": "Configured",
        "last_activated_date": "",
        "last_seen": "2025-04-16T21:42:03",
        "model": "Apple iPhone 13 Pro",
        "name": "My iPhone",
        "number": "15555550100",
        "os_version": "17.1",
        "phone_id": "DPFZRS9FB0D46QFTM899",
        "platform": "Apple iOS",
        "postdelay": "0",
        "predelay": "0",
        "screenlock": "Locked",
        "sms_passcodes_sent": true,
        "tampered": "Not tampered",
        "type": "Mobile"
        }
      ],
      "realname": "Joe Smith",
      "status": "active",
      "tokens": [
        {
        "serial": "123456",
        "token_id": "DHIZ34ALBA2445ND4AI2",
        "type": "d1"
        }
      ],
      "u2ftokens": [],
      "user_id": "DU3RP9I2WOC59VZX672N",
      "username": "jsmith",
      "webauthncredentials": [
        {
        "credential_name": "Touch ID",
        "date_added": 1550685154,
        "date_last_used": 1728064132,
        "label": "Touch ID",
        "webauthnkey": "WABFEOE007ZMV1QAZTRB"
        },
        {
        "credential_name": "YubiKey C",
        "date_added": 1550674764,
        "date_last_used": null,
        "label": "Security Key",
        "webauthnkey": "WA4BD9AUVMSNUFWZGES4"
        }
      ],
    },
    {
      "alias1": "chris.jones",
      "alias2": "cjones@example.com",
      "alias3": null,
      "alias4": null,
      "aliases": {
        "alias1": "chris.jones",
        "alias2": "cjones@example.com"
      },
      "created": 1489612829,
      "custom_attributes": {
          "Company": "Acme",
          "Employee ID": "8679053"
      },
      "desktop_authenticators": [],
      "email": "cjones@example.com",
      "enable_auto_prompt": false,
      "entra_federated_user_id": null,
      "firstname": "Chris",
      "groups": [],
      "is_enrolled": true,
      "last_directory_sync": null,
      "last_login": 1343821403,
      "lastname": "Jones",
      "notes": "",
      "phones": [
        {
        "activated": true,
        "app_version": "4.87.0",
        "capabilities": [
          "auto",
          "push",
          "sms",
          "phone",
          "mobile_otp"
        ],
        "creation_date": "",
        "encrypted": "Encrypted",
        "extension": "",
        "fingerprint": "Configured",
        "last_activated_date": "",
        "last_seen": "2019-09-24T17:42:46",
        "model": "Google Pixel 5",
        "name": "Pixel5",
        "number": "15555550200",
        "os_version": "14",
        "phone_id": "DPFZRS9FB0D46QFTP00L",
        "platform": "Google Android",
        "postdelay": "0",
        "predelay": "0",
        "screenlock": "Locked",
        "sms_passcodes_sent": false,
        "tampered": "Not tampered",
        "type": "Mobile"
        }
      ],
      "realname": "Chris Jones",
      "status": "active",
      "tokens": [],
      "u2ftokens": [],
      "user_id": "DU3RP9I2WOC59VZXJ05H",
      "username": "cjones",
      "webauthncredentials": [
        {
        "credential_name": "YubiKey",
        "date_added": 1550564764,
        "date_last_used": 1728064132,
        "label": "yubikey",
        "webauthnkey": "WA4BD9AUVMSNUFWZJ05H"
        }
      ]
    }
  ]
}

Create User

Create a new user with the specified username. Requires "Grant resource - Write" API permission.

POST /admin/v1/users

Parameters

Response Codes

Response Format

Returns the new single user object. Refer to Retrieve Users for an explanation of the object's keys.

Example Response

{
  "stat": "OK",
  "response":{
    "alias1": null,
    "alias2": null,
    "alias3": null,
    "alias4": null,
    "aliases": {},
    "created": 1657222760,
    "custom_attributes": {
      "Company": "Acme",
      "Employee ID": ""
    },
    "desktop_authenticators": [],
    "email": "jperez@example.com",
    "enable_auto_prompt": true,
    "entra_federated_user_id": null,
    "firstname": "Juan",
    "groups": [],
    "is_enrolled": false,
    "last_directory_sync": null,
    "last_login": null,
    "lastname": "Perez",
    "lockout_reason": null,
    "notes": "",
    "phones": [],
    "realname": "Juan Perez",
    "status": "active",
    "tokens": [],
    "u2ftokens": [],
    "user_id": "DU0W79YFWZAJWJV6P00L",
    "username": "jperez",
    "webauthncredentials": []
  }
}

Create Multiple Users

Create multiple users at once. If one user fails to add, the entire operation fails. You can create a maximum of 100 users per request at a rate limit of 50 calls per minute. Requires "Grant resource - Write" API permission.

POST /admin/v1/users/bulk_create

Parameters

User Object Attributes

Response Format

Returns a list of response objects, one for each operation provided. The response format for each operation will follow the same format as that of the corresponding single-operation endpoint for that operation. For example, a Create User operation will receive a response in the format described in Create User.

Note that it is possible for some operations to fail while others succeed. The list of responses can include both successful responses as well as unsuccessful responses due to invalid parameters or rate limiting.

Response Codes

Example Request

Here’s a sample python script that uses the admin api client to call out to the new endpoint. Note that the “users” param is a JSON serialized string.

{
#!/usr/bin/python
from __future__ import absolute_import
from __future__ import print_function
import pprint
import sys
import json

import duo_client
from six.moves import input

# Configuration and information about objects to create.
admin_api = duo_client.Admin(
    ikey='DIWJ8X6AEYOR5OMC6TQ1',
    skey='Zh5eGmUq9zpfQnyUIu5OL9iWoMMv5ZNmk3zLJ4Ep',
    host='api-XXXXXXXX.duosecurity.com',
    ca_certs='DISABLE'
)

response = admin_api.json_api_call(
    'POST',
    '/admin/v1/users/bulk_create',
    {
        'users': json.dumps([
            {
                'username': 'example_username_1',
                'email': 'example_user_1@example.com'
            },
            {
                'username': 'example_username_2',
                'status': 'disabled'
            }
        ])
    }
)

pprint.pprint(response)
}

Example Response

Here’s the output from running the above script. Note that the shape of the user objects returned here is consistent with the shape returned from other Admin API user operations (e.g. creating a single user). The returned users will be in the same order that they were received.

{
  "[{'alias1': None,
  'alias2': None,
  'alias3': None,
  'alias4': None,
  'aliases': {},
  'created': 1677770740,
  'email': 'example_user_1@example.com',
  'firstname': None,
  'groups': [],
  'is_enrolled': False,
  'last_directory_sync': None,
  'last_login': None,
  'lastname': None,
  'lockout_reason': "null",
  'notes': '',
  'phones': [],
  'realname': '',
  'status': 'active',
  'tokens': [],
  'u2ftokens': [],
  'user_id': 'DUVI0UT8SKB5P70WG42Z',
  'username': 'example_username_1',
  'webauthncredentials': []},
 {'alias1': None,
  'alias2': None,
  'alias3': None,
  'alias4': None,
  'aliases': {},
  'created': 1677770740,
  'email': '',
  'firstname': None,
  'groups': [],
  'is_enrolled': False,
  'last_directory_sync': None,
  'last_login': None,
  'lastname': None,
  'notes': '',
  'phones': [],
  'realname': '',
  'status': 'disabled',
  'tokens': [],
  'u2ftokens': [],
  'user_id': 'DU2X1VOO31O10F2ZNF43',
  'username': 'example_username_2',
  'webauthncredentials': []}]
  }
}

Restore Multiple Users from Trash

Restore multiple users from the Trash at once. If one user fails to restore, the entire operation fails. You can restore a maximum of 100 users per request at a rate limit of 50 calls per minute. Restoring users from the Trash doesn't change the user's status. Restored users still have a "disabled" status and can't log in. Refer to Restoring Users from Trash for more information. Requires "Grant resource - Write" API permission.

POST /admin/v1/users/bulk_restore

Parameters

Response Format

Returns a string indicating how many users were restored from the Trash.

Response Codes

Example Response

{
    "response": "Restored 2 users from the trash",
    "stat": "OK"
}

Send Multiple Users to Trash

Send multiple users to Trash. Once a user is in the Trash, the user is pending deletion for 7 days before being permanently deleted. Refer to Deleting and Restoring Users for more information.

POST /admin/v1/users/bulk_send_to_trash

Parameters

Response Format

Returns a string with the number of users sent to the Trash.

Response Codes

Example Response

{
  "response": [
    {"user_id": "DU123456789012345678", "success": true},
    {"user_id": "DU234567890123456789", "success": false, "error": "Users managed by directory sync cannot be sent to the trash"},
  ],
  "stat": "OK"
}

Retrieve User by ID

Return the single user with user_id. Requires "Grant resource - Read" API permission.

GET /admin/v1/users/[user_id]

Parameters

This API endpoint has no parameters.

Response Codes

Response Format

Returns a single user object. Refer to Retrieve Users for an explanation of the object's keys.

Example Response

{
  "stat": "OK",
  "response": {
    "alias1": "joe.smith",
    "alias2": "jsmith@example.com",
    "alias3": null,
    "alias4": null,
    "aliases": {
      "alias1": "joe.smith",
      "alias2": "jsmith@example.com"
    },
    "created": 1489612729,
    "directory_key": "DABC0DEFGHIJKLMNOPQR",
    "email": "jsmith@example.com",
    "enable_auto_prompt": true,
    "external_id": "1a2345b6-7cd8-9e0f-g1hi-23j45kl6m789",
    "firstname": "Joe",
    "groups": [
      {
      "desc": "People with hardware tokens",
      "group_id": "DGBDKSSH37KSJ373JKSU",
      "mobile_otp_enabled": false,
      "name": "token_users",
      "push_enabled": false,
      "sms_enabled": false,
      "status": "Active",
      "voice_enabled": false
      }
    ],
    "is_enrolled": true,
    "last_directory_sync": 1508789163,
    "last_login": 1343921403,
    "lastname": "Smith",
    "lockout_reason": null,
    "notes": "",
    "phones": [
      {
      "activated": true,
      "app_version": "4.86.0",
      "capabilities": [
        "auto",
        "push",
        "sms",
        "phone",
        "mobile_otp"
        ],
      "creation_date": "",
      "encrypted": "Encrypted",
      "extension": "",
      "fingerprint": "Configured",
      "last_activated_date": "",
      "last_seen": "2024-11-18T15:51:13",
      "model": "Apple iPhone 13 Pro",
      "name": "My iPhone",
      "os_version": "17.1",
      "number": "15555550100",
      "phone_id": "DPFZRS9FB0D46QFTM899",
      "platform": "Apple iOS",
      "postdelay": "0",
      "predelay": "0",
      "screenlock": "Locked",
      "sms_passcodes_sent": true,
      "tampered": "Not tampered",
      "type": "Mobile"
      }
    ],
    "realname": "Joe Smith",
    "status": "active",
    "tokens": [
      {
      "serial": "123456",
      "token_id": "DHIZ34ALBA2445ND4AI2",
      "type": "d1"
      }
    ],
    "u2ftokens": [],
    "user_id": "DU3RP9I2WOC59VZX672N",
    "username": "jsmith",
    "webauthncredentials": [
      {
      "credential_name": "Touch ID",
      "date_added": 1550685154,
      "date_last_used": 1728064132,
      "label": "Touch ID",
      "webauthnkey": "WABFEOE007ZMV1QAZTRB"
      },
      {
      "credential_name": "YubiKey C",
      "date_added": 1550674764,
      "date_last_used": null,
      "label": "Security Key",
      "webauthnkey": "WA4BD9AUVMSNUFWZGES4"
      }
    ],
  }
}

Modify User

Change the username, username aliases, full name, status, and/or notes section of the user with ID user_id. Requires "Grant resource - Write" API permission.

POST /admin/v1/users/[user_id]

Parameters

Response Codes

Response Format

Returns the modified single user object. Refer to Retrieve Users for an explanation of the object's keys.

Example Response

Same as Retrieve User by ID.

Delete User

Delete the user with ID user_id from the system. The API will not delete phones associated only with that user right away; remove them immediately with Delete Phone. This method returns 200 if the phone was found or if no such phone exists. Requires "Grant resource - Write" API permission.

Users deleted by the API do not get moved into the Trash view as "Pending Deletion" as they would if removed by directory sync, user deletion, or interactively from the Duo Admin Panel, and therefore are not available for restoration. Users deleted via the API are immediately and permanently removed from Duo.

To send multiple users to the Trash, see Send Multiple Users to Trash.

DELETE /admin/v1/users/[user_id]

Parameters

This API endpoint has no parameters.

Response Codes

Response Format

Empty string.

Example Response

{
  "stat": "OK",
  "response": ""
}

Enroll User

Enroll a user with user name username and email address email and send them an enrollment email that expires after valid_secs seconds. Requires "Grant resource - Write" API permission.

POST /admin/v1/users/enroll

Parameters

Response Codes

Response Format

Single string (the enrollment code).

Example Response

{
  "stat": "OK",
  "response": "00d70e730b22cb66"
}

Create Bypass Codes for User

Clear all existing bypass codes for the user with ID user_id and return a list of count newly generated bypass codes, or specify codes that expire after valid_secs seconds, or reuse_count uses. To preserve existing bypass codes instead of clearing them the request must specify preserve_existing=true.

Requires "Grant resource - Write" API permission.

Object limits: 100 bypass codes per user.

POST /admin/v1/users/[user_id]/bypass_codes

Parameters

Response Codes

Response Format

List of strings.

Example Response

{
  "stat": "OK",
  "response": [
    "407176182",
    "016931781",
    "338390347",
    "537828175",
    "006165274",
    "438680449",
    "877647224",
    "196167433",
    "719424708",
    "727559878"
  ]
}

Retrieve Bypass Codes by User ID

Returns a paged list of bypass code metadata associated with the user with ID user_id. To fetch all results, call repeatedly with the offset parameter as long as the result metadata has a next_offset value. Does not return the actual bypass codes. Requires "Grant resource - Read" API permission.

GET /admin/v1/users/[user_id]/bypass_codes

Parameters

Use the paging parameters to change the number of results shown in a response or to retrieve additional results. See Response Paging for details.

This API endpoint has no additional parameters.

Response Codes

Response Format

Example Response

{
  "stat": "OK",
  "response": [
    {
    "admin_email": "janesmith@example.com",
    "bypass_code_id": "DB2A9F0012RL54001FA3",
    "created": 1522260759,
    "expiration": 1522264359,
    "reuse_count": 1
    }
  ]
}

Retrieve Groups by User ID

Returns a paged list of groups associated with the user with ID user_id. To fetch all results, call repeatedly with the offset parameter as long as the result metadata has a next_offset value. Requires "Grant resource - Read" API permission.

GET /admin/v1/users/[user_id]/groups

Parameters

Use the paging parameters to change the number of results shown in a response or to retrieve additional results. See Response Paging for details.

This API endpoint has no additional parameters.

Response Codes

Response Format

Returns the groups for the user object. Refer to Retrieve Groups for an explanation of the object keys.

Example Response

{
  "stat": "OK",
  "response": [
    {
    "desc": "This is group A",
    "group_id": "DGBDKSSH37KSJ373JKSU",
    "mobile_otp_enabled": false,
    "name": "Group A",
    "push_enabled": false,
    "sms_enabled": false,
    "status": "active",
    "voice_enabled": false
    },
    {
    "desc": "This is group B",
    "group_id": "DGJKSLSH393YSJD93HSD3",
    "mobile_otp_enabled": false,
    "name": "Group B (from Microsoft Entra ID sync \"Acme Corp Entra ID\")",
    "push_enabled": false,
    "sms_enabled": false,
    "status": "active",
    "voice_enabled": false
    }
  ]
}

Associate Group with User

Associate a group with ID group_id with the user with ID user_id. Requires "Grant resource - Write" API permission.

Object limits: 100 groups per user.

POST /admin/v1/users/[user_id]/groups

Parameters

Response Codes

Response Format

Empty string.

Example Response

{
  "stat": "OK",
  "response": ""
}

Disassociate Group from User

Disassociate a group from the user with ID user_id. This method will return 200 if the group was found or if no such group exists. Requires "Grant resource - Write" API permission.

DELETE /admin/v1/users/[user_id]/groups/[group_id]

Parameters

This API endpoint has no parameters.

Response Codes

Response Format

Empty string.

Example Response

{
  "stat": "OK",
  "response": ""
}

Retrieve Phones by User ID

Returns a paged list of phones associated with the user with ID user_id. To fetch all results, call repeatedly with the offset parameter as long as the result metadata has a next_offset value. Requires "Grant resource - Read" API permission.

GET /admin/v1/users/[user_id]/phones

Parameters

Use the paging parameters to change the number of results shown in a response or to retrieve additional results. See Response Paging for details.

This API endpoint has no additional parameters.

Response Codes

Response Format

Same as for Retrieve Phones, except phones have no users attribute.

Example Response

{
  "stat": "OK",
  "response": [
    {
    "activated": true,
    "app_version": "4.85.0",
    "capabilities": [
      "auto",
      "push",
      "sms",
      "phone",
      "mobile_otp"
    ],
    "creation_date": "",
    "encrypted": "Encrypted",
    "extension": "",
    "fingerprint": "Configured",
    "last_activated_date": "",
    "last_seen": "2025-03-04T15:04:04",
    "model": "Google Pixel 6",
    "os_version": "14",
    "name": "",
    "number": "+15035550102",
    "phone_id": "DPFZRS9FB0D46QFTM890",
    "platform": "Google Android",
    "postdelay": "",
    "predelay": "",
    "screenlock": "Locked",
    "sms_passcodes_sent": true,
    "tampered": "Not tampered",
    "type": "Mobile"
    },
    {
    "activated": false,
    "app_version": "",
    "capabilities": [
      "phone"
    ],
    "creation_date": "",
    "encrypted": "",
    "extension": "",
    "fingerprint": "",
    "last_activated_date": "",
    "last_seen": "",
    "model": "Unknown",
    "name": "",
    "number": "+15035550103",
    "os_version": "",
    "phone_id": "DPFZRS9FB0D46QFTM891",
    "platform": "Unknown",
    "postdelay": "",
    "predelay": "",
    "screenlock": "",
    "sms_passcodes_sent": false,
    "tampered": "",
    "type": "Landline"
    }
  ]
}

Associate Phone with User

Associate a phone with the user with ID user_id. Requires "Grant resource - Write" API permission.

Object limits: 100 phones per user; 100 users per phone.

POST /admin/v1/users/[user_id]/phones

Parameters

Response Codes

Response Format

Empty string.

Example Response

{
  "stat": "OK",
  "response": ""
}

Disassociate Phone from User

Disassociate a phone from the user with ID user_id. The API will not automatically delete the phone after removing the last user association; remove it permanently with Delete Phone. This method returns 200 if the phone was found or if no such phone exists. Requires "Grant resource - Write" API permission.

DELETE /admin/v1/users/[user_id]/phones/[phone_id]

Parameters

This API endpoint has no parameters.

Response Codes

Response Format

Empty string.

Example Response

{
  "stat": "OK",
  "response": ""
}

Retrieve Hardware Tokens by User ID

Returns a paged list of OTP hardware tokens associated with the user with ID user_id. To fetch all results, call repeatedly with the offset parameter as long as the result metadata has a next_offset value. Requires "Grant resource - Read" API permission.

GET /admin/v1/users/[user_id]/tokens

Parameters

Use the paging parameters to change the number of results shown in a response or to retrieve additional results. See Response Paging for details.

This API endpoint has no additional parameters.

Response Codes

Response Format

Same as for Retrieve Hardware Tokens, except hardware tokens have no admins or users attribute.

Example Response

{
  "stat": "OK",
  "response": [
    {
    "serial": "123456",
    "token_id": "DHEKH0JJIYC1LX3AZWO4",
    "totp_step": null,
    "type": "d1"
    },
    {
    "serial": "123457",
    "token_id": "DHUNT3ZVS3ACF8AEV2WG",
    "totp_step": null,
    "type": "d1"
    }
  ]
}

Associate Hardware Token with User

Associate a hardware token with the user with ID user_id. Requires "Grant resource - Write" API permission.

Object limits: 100 tokens per user.

POST /admin/v1/users/[user_id]/tokens

Parameters

Response Codes

Response Format

Empty string.

Example Response

{
  "stat": "OK",
  "response": ""
}

Disassociate Hardware Token from User

Disassociate a hardware token from the user with ID user_id. This method will return 200 if the hardware token was found or if no such hardware token exists. Requires "Grant resource - Write" API permission.

DELETE /admin/v1/users/[user_id]/tokens/[token_id]

Parameters

This API endpoint has no parameters.

Response Codes

Response Format

Empty string.

Example Response

{
  "stat": "OK",
  "response": ""
}

Retrieve U2F Tokens by User ID

The U2F Tokens by User ID API endpoint /admin/v1/users/[user_id]/u2ftokens is deprecated as of February 2022. This API no longer allows listing all U2F tokens for a user. Requests to this endpoint now fail with the following response:

{
  "stat": "FAIL",
  "code": 40301,
  "message": "Access forbidden",
}

Retrieve WebAuthn Credentials by User ID

Returns a list of WebAuthn credentials associated with the user with ID user_id. Requires "Grant resource - Read" API permission.

GET /admin/v1/users/[user_id]/webauthncredentials

Parameters

This API endpoint has no parameters.

Response Codes

Response Format

Example Response

{
  "response": [
    {
      "credential_name": "YubiKey 5",
      "date_added": 1550674764,
      "date_last_used": 1728064132,
      "label": "Security Key",
      "webauthnkey": "WA4ED9AUVMSWUF00KES4"
    }
  ],
  "stat": "OK"
}

Retrieve Desktop Authenticators by User ID

Returns a paged list of desktop authenticators associated with the user with ID user_id. To fetch all results, call repeatedly with the offset parameter as long as the result metadata has a next_offset value. Requires "Grant resource - Read" API permission.

GET /admin/v1/users/[user_id]/desktopauthenticators

Parameters

This API endpoint has no additional parameters.

Response Codes

Response Format

Example Response

{
  "response": [
    {
      "daid": 365,
      "dakey": "DDABCDE1FGHIJ23KL45",
      "device_name": "DESKTOP-ABC1234",
      "duo_desktop_version": "6.12.0",
      "os_family": "Windows"
    }
  ],
  "stat": "OK"
}

Synchronize User from Directory

Initiate a sync to create, update, or mark for deletion the user specified by username against the directory specified by the directory_key. The directory_key for a directory can be found by navigating to Users → Directory Sync in the Duo Admin Panel, and then clicking on the configured directory. Learn more about syncing individual users from Active Directory, OpenLDAP, or Entra ID. Requires "Grant resource - Write" API permission.

POST /admin/v1/users/directorysync/[directory_key]/syncuser

Parameters

Response Codes

Response Format

Returns the single synced user object with an additional message stating the user synced successfully. Refer to Retrieve Users for an explanation of the object's keys.

Example Response

{
  "stat": "OK",
  "response":{
    "message": "User wwu synced successfully.",
    "user": {
      "alias1": "wwu@example.com",
      "alias2": null,
      "alias3": null,
      "alias4": null,
      "aliases": {
        "alias1": "wwu@example.com"
      },
      "created": 1553271753,
      "directory_key": "DABC0DEFGHIJKLMNOPQR",
      "email": "",
      "enable_auto_prompt": true,
      "external_id": "1a2345b6-7cd8-9e0f-g1hi-23j45kl6m789",
      "firstname": "",
      "groups": [
        {
        "desc": "",
        "group_id": "DGKAT4WCV306FOONUNIC",
        "mobile_otp_enabled": false,
        "name": "Duo Users (from AD sync \"Acme Sync")",
        "push_enabled": false,
        "sms_enabled": false,
        "status": "Active",
        "voice_enabled": false
        }
      ],
      "is_enrolled": true,
      "last_directory_sync": 1657227493,
      "last_login": 1553271773,
      "lastname": "",
      "lockout_reason": null,
      "notes": "",
      "phones": [],
      "realname": "Wang Wu",
      "status": "active",
      "tokens": [],
      "u2ftokens": [],
      "user_id": "DUYGKDZI47WEJIIXU6QI",
      "username": "wwu",
      "webauthncredentials": [
        {
        "credential_name": "YubiKey",
        "date_added": 1553271760,
        "date_last_used": 1728064132,
        "label": "Security Key",
        "webauthnkey": "WAYRDI633R1219HM1BN7"
        }
      ]
    }
  }
}

Send Verification Push

Sends a verification Duo Push to the user with ID user_id. Verification pushes can also be sent from the Duo Admin Panel. Requires "Grant resource - Write" API permission.

POST /admin/v1/users/[user_id]/send_verification_push

Parameters

Response Codes

Response Format

Example Response

{
  "response": {
    "confirmation_code": "123456",
    "push_id": "123abc45-6def-789g-h012-34567ijk8901"
  },
  "stat": "OK"
}

Retrieve Verification Push Response

Retrieves the verification push result for the user with ID user_id. Push response information will be available for 120 seconds after the push was sent, after which this endpoint will return a 404. If no success or failure response was returned by this endpoint during these 120 seconds, it can be assumed that the push has timed out. Requires "Grant resource - Read" API permission.

GET /admin/v1/users/[user_id]/verification_push_response

Parameters

Response Codes

Response Format

Example Response

{
  "response": {
    "push_id": "123abc45-6def-789g-h012-34567ijk8901"
    "result": "approve"
  },
  "stat": "OK"
}

Bulk Operations

Bulk User Operations

Performs a list of operations serially in the order provided. You can perform a maximum of 50 operations per request at a rate limit of 50 calls per minute. Requires "Grant resource - Write" API permission.

POST /admin/v1/bulk

Parameters

Operations

Each operation must be a JSON object that specifies the following attributes.

Valid Operations

Response Codes

Response Format

Returns a list of response objects, one for each operation provided. The response format for each operation will follow the same format as that of the corresponding single-operation endpoint for that operation. For example, a Create User operation will receive a response in the format described in Create User.

Note that it is possible for some operations to fail while others succeed. The list of responses can include both successful responses as well as unsuccessful responses due to invalid parameters or rate limiting.

Example Operations list

This sample list of operations provides an example of what should be passed as the operations parameter.

{
[
	{
		"method": "POST",
		"path": "/admin/v1/users",
		"body": {
			"username": "uname1",
			"alias1": "my_alias1",
			"alias2": "my_alias2",
			"alias3": "my_alias3",
			"alias4": "my_alias4",
			"email": "user@example.com",
			"status": "active",
			"notes": "This is a user"
		}
	},
	{
		"method": "POST",
		"path": "/admin/v1/users/DUJ424R8DJFJ05HASDFJ",
		"body": {
			"username": "uname2",
			"alias2": "updated_alias2",
			"email": "user2@example.com",
			"status": "active",
			"notes": "This is another user"
		}
	},
	{
		"method": "DELETE",
		"path": "/admin/v1/users/DUJ424R8DJFJ05HASDFJ",
		"body": {}
	},
	{
		"method": "POST",
		"path": "/admin/v1/users/DUJ424R8DJFJ05HASDFJ/groups",
		"body": {
			"group_id": "DGBDKSSH37KSJ373JKSU",
		}
	},
	{
		"method": "DELETE",
		"path": "/admin/v1/users/DUJ424R8DJFJ05HASDFJ/groups/DGBDKSSH37KSJ373JKSU",
		"body": {}
	}
]

}

Example Response

{
[
	{
	  "stat": "OK",
	  "response":{
	    "alias1": "my_alias1",
	    "alias2": "my_alias2",
	    "alias3": "my_alias3",
	    "alias4": "my_alias4",
	    "aliases": {
	    	"alias1": "my_alias1",
		    "alias2": "my_alias2",
		    "alias3": "my_alias3",
		    "alias4": "my_alias4",
	    },
	    "created": 1657222760,
	    "email": "user@example.com",
      "enable_auto_prompt": true,
	    "firstname": "",
	    "groups": [],
	    "is_enrolled": false,
	    "last_directory_sync": null,
	    "last_login": null,
	    "lastname": "",
      "lockout_reason": null,
	    "notes": "This is a user",
	    "phones": [],
	    "realname": "",
	    "status": "active",
	    "tokens": [],
	    "u2ftokens": [],
	    "user_id": "DUJ424R8DJFJ05HASDFJ",
	    "username": "uname1",
	    "webauthncredentials": []
	  }
	},
	{
	  "stat": "OK",
	  "response":{
	    "alias1": null,
	    "alias2": "my_alias2",
	    "alias3": null,
	    "alias4": null,
	    "aliases": {
		    "alias2": "updated_alias2",
	    },
	    "created": 1657223860,
	    "email": "user2@example.com",
      "enable_auto_prompt": true,
	    "firstname": "",
	    "groups": [],
	    "is_enrolled": false,
	    "last_directory_sync": null,
	    "last_login": null,
	    "lastname": "",
      "lockout_reason": null,
	    "notes": "This is another user",
	    "phones": [],
	    "realname": "",
	    "status": "active",
	    "tokens": [],
	    "u2ftokens": [],
	    "user_id": "DUJ424R8DP0OL5D4DAFJ",
	    "username": "uname2",
	    "webauthncredentials": []
	  }
	},
	{
  		"stat": "OK",
  		"response": ""
	},
	{
  		"stat": "OK",
  		"response": ""
	},
	{
  		"stat": "OK",
  		"response": ""
	}
]

}

Groups

Per-user Group Operations

See Retrieve Groups by User ID, Associate Group with User, and Disassociate Group from User.

Retrieve Groups

Returns a paged list of groups. To fetch all results, call repeatedly with the offset parameter as long as the result metadata has a next_offset value. Requires "Grant resource - Read" API permission.

GET /admin/v1/groups

Parameters

Use the paging parameters to change the number of results shown in a response or to retrieve additional results. See Response Paging for details.

This API endpoint has no additional parameters.

Response Codes

Response Format

Example Response

{
  "stat": "OK",
  "response": [
    {
    "desc": "This is group A",
    "group_id": "DGBDKSSH37KSJ373JKSU",
    "mobile_otp_enabled": false,
    "name": "Group A",
    "push_enabled": false,
    "sms_enabled": false,
    "status": "Active",
    "voice_enabled": false
    },
    {
    "desc": "This is group B",
    "group_id": "DGJKSLSH393YSJD93HSD3",
    "mobile_otp_enabled": false,
    "name": "Group B (from Microsoft Entra ID sync \"Acme Corp Entra ID\")",
    "push_enabled": false,
    "sms_enabled": false,
    "status": "Active",
    "voice_enabled": false
    }
  ],
}

Create Group

Create a new group. Requires "Grant resource - Write" API permission.

POST /admin/v1/groups

Parameters

Response Codes

Response Format

Example Response

{
  "stat": "OK",
  "response": {
    "desc": "This is an example group",
    "group_id": "DGBDKSSH37KSJ373JKSU",
    "mobile_otp_enabled": false,
    "name": "Example Group",
    "push_enabled": false,
    "sms_enabled": false,
    "status": "active",
    "voice_enabled": false
  }
}

Get Group Info

Retrieve information about a group. Note that this output does not include a list of group members. To retrieve group members, use /admin/v2/groups/[group_id]/users. Requires "Grant resource - Read" API permission.

GET /admin/v2/groups/[group_id]

Parameters

This API endpoint has no parameters.

Response Codes

Response Format

Example Response

{
  "stat": "OK",
  "response": {
    "desc": "Group description",
    "group_id": "DGBDKSSH37KSJ373JKSU",
    "mobile_otp_enabled": false,
    "name": "Group Name",
    "push_enabled": false,
    "sms_enabled": false,
    "status": "active",
    "voice_enabled": false
  }
}

Get Group Members

Returns a paged list of members of a specified group. To fetch all results, call repeatedly with the offset parameter as long as the result metadata has a next_offset value.

GET /admin/v2/groups/[group_id]/users

Parameters

Use the paging parameters to change the number of results shown in a response or to retrieve additional results. See Response Paging for details.

Response Codes

Response Format

Example Response

{
  "stat": "OK",
  "metadata": {
      "total_objects": 4
  },
  "response": [
      {
          "user_id": "DUJF3424R8DJFJ05HASD",
          "username": "user1"
      },
      {
          "user_id": "DUJSFP005D4DJFJ05HSD",
          "username": "user2"
      },
      {
          "user_id": "DUJSFP001D4DJFJB0OFS",
          "username": "user3"
      }
  ]
}

Update Group

Update information about a group. Requires "Grant resource - Write" API permission.

POST /admin/v1/groups/[group_id]

Parameters

Response Codes

Response Format

Example Response

{
  "stat": "OK",
  "response": {
    "desc": "Group description",
    "group_id": "DGBDKSSH37KSJ373JKSU",
    "mobile_otp_enabled": false,
    "name": "Group Name",
    "push_enabled": false,
    "sms_enabled": false,
    "status": "active",
    "voice_enabled": false
  }
}

Delete Group

Delete a group. Requires "Grant resource - Write" API permission.

DELETE /admin/v1/groups/[group_id]

Parameters

This API endpoint has no parameters.

Response Codes

Response Format

Empty string.

Example Response

{
  "response": "",
  "stat": "OK"
}

Phones

Per-user Phone Operations

See Retrieve Phones by User ID, Associate Phone with User, and Disassociate Phone from User.

Retrieve Phones

Returns a paged list of phones. To fetch all results, call repeatedly with the offset parameter as long as the result metadata has a next_offset value. If no number or extension parameters are provided, the list will contain all phones. Otherwise, the list will contain either single phone (if a match was found), or no phones. Requires "Grant resource - Read" API permission.

GET /admin/v1/phones

Parameters

Use the paging parameters to change the number of results shown in a response or to retrieve additional results. See Response Paging for details.

Response Codes

Response Format

Example Response

{
  "stat": "OK",
  "response": [
    {
      "activated": true,
      "app_version": "4.86.0",
      "capabilities": [
        "auto",
        "push",
        "sms",
        "phone",
        "mobile_otp"
      ],
      "creation_date": "2025-01-29T08:08:16",
      "encrypted": "Encrypted",
      "extension": "",
      "fingerprint": "Configured",
      "last_activated_date": "2025-01-29T08:14:40",
      "last_seen": "2025-04-16T21:42:03",
      "model": "Apple iPhone 15 Pro",
      "name": "My iPhone",
      "number": "15555550100",
      "os_version": "14",
      "phone_id": "DPFZRS9FB0D46QFTM899",
      "platform": "Apple iOS",
      "postdelay": "",
      "predelay": "",
      "screenlock": "Locked",
      "sms_passcodes_sent": false,
      "tampered": "Not tampered",
      "type": "Mobile",
      "users": [
        {
        "alias1": "joe.smith",
        "alias2": "jsmith@example.com"
        "alias3": null,
        "alias4": null,
        "aliases": {
          "alias1": "joe.smith",
          "alias2": "jsmith@example.com"
        },
        "created": 1509717442,
        "email": "jsmith@example.com",
        "enable_auto_prompt": true,
        "firstname": "",
        "is_enrolled": false,
        "last_directory_sync": null,
        "last_login": 1474399627,
        "lastname": "",
        "notes": "",
        "realname": "Joe Smith",
        "status": "active",
        "user_id": "DUJZ2U4L80HT45MQ4EOQ",
        "username": "jsmith"
        }
      ]
    },
    {
      "activated": true,
      "app_version": "4.87.0",
      "capabilities": [
        "auto",
        "push",
        "sms",
        "phone",
        "mobile_otp"
      ],
      "creation_date": "2025-01-29T08:08:16",
      "encrypted": "Encrypted",
      "extension": "",
      "fingerprint": "Configured",
      "last_activated_date": "2025-01-29T08:14:40",
      "last_seen": "2025-04-16T21:42:03",
      "model": "Google Pixel 8",
      "name": "Pixel 8",
      "number": "15555550200",
      "os_version": "14",
      "phone_id": "DPFZRS9FB0D46QFTP00L",
      "platform": "Google Android",
      "postdelay": "0",
      "predelay": "0",
      "screenlock": "Locked",
      "sms_passcodes_sent": false,
      "tampered": "Not tampered",
      "type": "Mobile"
      "users": [
        {
        "alias1": "chris.jones",
        "alias2": "cjones@example.com",
        "alias3": null,
        "alias4": null,
        "aliases": {
          "alias1": "chris.jones",
          "alias2": "cjones@example.com"
        },
        "created": 1489612829,
        "email": "cjones@example.com",
        "enable_auto_prompt": true,
        "firstname": "",
        "groups": [],
        "is_enrolled": true,
        "last_directory_sync": null,
        "last_login": 1343821403,
        "lastname": "",
        "notes": "",
        "realname": "Chris Jones",
        "status": "active",
        "user_id": "DU3RP9I2WOC59VZXJ05H",
        "username": "cjones"
        }
      ]
    }
  ]
}

Create Phone

Create a new phone with a specified phone number or other parameters. Requires "Grant resource - Write" API permission.

POST /admin/v1/phones

Parameters

Response Codes

Response Format

Returns the single phone object created. Refer to Retrieve Phones for an explanation of the object's keys.

Example Response

{
  "stat": "OK",
  "response":{
    "activated": false,
    "capabilities": [],
    "extension": "",
    "last_seen": "",
    "model": "Unknown",
    "name": "",
    "number": "15555551111",
    "phone_id": "DP1D9EZJNZNQXJ05HKJB",
    "platform": "Generic Smartphone",
    "postdelay": "",
    "predelay": "",
    "sms_passcodes_sent": false,
    "type": "Unknown",
    "users": []
    }
}

Retrieve Phone by ID

Return the single phone with phone_id. Requires "Grant resource - Read" API permission.

GET /admin/v1/phones/[phone_id]

Parameters

This API endpoint has no parameters.

Response Codes

Response Format

Returns a single phone object. Refer to Retrieve Phones for an explanation of the object's keys.

Example Response

{
  "stat": "OK",
  "response": {
    "activated": true,
    "app_version": "4.87.0",
    "capabilities": [
      "auto",
      "push",
      "sms",
      "phone",
      "mobile_otp"
    ],
    "creation_date": "",
    "encrypted": "Encrypted",
    "extension": "",
    "fingerprint": "Configured",
    "last_activated_date": "",
    "last_seen": "2025-04-16T21:42:03",
    "model": "Google Pixel 8",
    "name": "",
    "number": "+15555550100",
    "os_version": "14",
    "phone_id": "DPFZRS9FB0D46QFTM899",
    "platform": "Google Android",
    "postdelay": "",
    "predelay": "",
    "screenlock": "Locked",
    "sms_passcodes_sent": false,
    "tampered": "Not tampered",
    "type": "Mobile",
    "users": [
      {
        "alias1": "joe.smith",
        "alias2": "jsmith@example.com"
        "alias3": null,
        "alias4": null,
        "aliases": {
          "alias1": "joe.smith",
          "alias2": "jsmith@example.com"
        },
        "created": 1509717442,
        "email": "jsmith@example.com",
        "enable_auto_prompt": true,
        "firstname": "",
        "is_enrolled": false,
        "last_directory_sync": null,
        "last_login": 1474399627,
        "lastname": "",
        "notes": "",
        "realname": "Joe Smith",
        "status": "active",
        "user_id": "DUJZ2U4L80HT45MQ4EOQ",
        "username": "jsmith",
      }
    ]
  }
}

Modify Phone

Change the details of the phone with ID phone_id. Requires "Grant resource - Write" API permission.

POST /admin/v1/phones/[phone_id]

Parameters

Response Codes

Response Format

Returns the modified single phone object. Refer to Retrieve Phones for an explanation of the object's keys.

Example Response

Same as Retrieve Phone by ID.

Delete Phone

Delete the phone with ID phone_id from the system. Requires "Grant resource - Write" API permission.

DELETE /admin/v1/phones/[phone_id]

Parameters

This API endpoint has no parameters.

Response Codes

Response Format

Empty string.

Example Response

{
  "stat": "OK",
  "response": ""
}

Create Activation Code

Generate a Duo Mobile activation code. This method will fail if the phone's type or platform are Unknown. Requires "Grant resource - Write" API permission.

POST /admin/v1/phones/[phone_id]/activation_url

Parameters

Response Codes

Response Format

Example Response

{
  "stat": "OK",
  "response": {
    "activation_barcode": "https://api-abcdefgh.duosecurity.com/frame/qr?value=duo%3A%2F%2Factivation-code",
    "activation_url": "https://m-abcdefgh.duosecurity.com/iphone/7dmi4Oowz5g3J47FARLs",
    "valid_secs": 3600
  }
}

Send Activation Code via SMS

Generate a Duo Mobile activation code and send it to the phone via SMS, optionally sending an additional message with a URL to install Duo Mobile. This method will fail if the phone's type or platform are Unknown. Requires "Grant resource - Write" API permission.

POST /admin/v1/phones/[phone_id]/send_sms_activation

Parameters

Response Codes

Response Format

Example Response

{
  "stat": "OK",
  "response": {
    "activation_barcode": "https://api-abcdef/frame/qr\?*value=duo%3A%2F%2FXoudqt8a9F-Jqt",
    "activation_msg": "To activate the Duo Mobile app, click this link: https://m-eval.duosecurity.com/iphone/7dmi4Oowz5g3J47FARLs",
    "installation_msg": "Welcome to Duo! To install the Duo Mobile app, click this link: http://m-eval.duosecurity.com",
    "valid_secs": 3600
  }
}

Send Installation URL via SMS

Send a message via SMS describing how to install Duo Mobile. This method will fail if the phone's type or platform are Unknown. Requires "Grant resource - Write" API permission.

POST /admin/v1/phones/[phone_id]/send_sms_installation

Parameters

Response Codes

Response Format

Example Response

{
  "stat": "OK",
  "response": {
    "installation_msg": "Welcome to Duo! To install the Duo Mobile app, click this link: http://m-abcdef.duosecurity.com"
  }
}

Send Passcodes via SMS

Generate a new batch of SMS passcodes send them to the phone in a single SMS message. Requires "Grant resource - Write" API permission.

POST /admin/v1/phones/[phone_id]/send_sms_passcodes

Parameters

This API endpoint has no parameters.

Response Codes

Response Format

Empty string.

Example Response

{
  "stat": "OK",
  "response": ""
}

Tokens

Per-user Token Operations

See Retrieve Hardware Tokens by User ID, Associate Hardware Token with User, and Disassociate Hardware Token from User.

Per-administrator Token Operations

See Retrieve Administrator by ID, Create Administrator, and Modify Administrator. Note that token information retrieved from the Tokens endpoint does not include information about administrators associated with a token, just end-users.

Retrieve Hardware Tokens

Returns a paged list of OTP hardware tokens. To fetch all results, call repeatedly with the offset parameter as long as the result metadata has a next_offset value. If no type and serial parameters are provided, the list will contain all hardware tokens. Otherwise, the list will contain either a single hardware token (if a match was found) or no hardware tokens. Requires "Grant resource - Read" API permission.

GET /admin/v1/tokens

Parameters

Use the paging parameters to change the number of results shown in a response or to retrieve additional results. See Response Paging for details.

Response Codes

Response Format

Example Response

{
  "stat": "OK",
  "response": [
    {
      "admins": [
        {
        "admin_id": "DESMP00LIAKRJPD4DZSH",
        "created": 1648143942,
        "email": "jsmith@example.com",
        "last_login": 1343921403,
        "name": "Joe Smith"
        }
      ],
      "serial": "123456",
      "token_id": "DHIZ34ALBA2445ND4AI2",
      "totp_step": null,
      "type": "d1",
      "users": [
        {
        "alias1": "joe.smith",
        "alias2": "jsmith@example.com",
        "alias3": null,
        "alias4": null,
        "aliases": {
          "alias1": "joe.smith",
          "alias2": "jsmith@example.com"
        },
        "created": 1343621411,
        "email": "jsmith@example.com",
        "enable_auto_prompt": true,
        "firstname": "",
        "is_enrolled": true,
        "last_directory_sync": null,
        "last_login": 1343921403,
        "lastname": "",
        "notes": "",
        "realname": "Joe Smith",
        "status": "active",
        "user_id": "DUJZ2U4L80HT45MQ4EOQ",
        "username": "jsmith"
        }
      ]
    }
  ]
}

Create Hardware Token

Create a new hardware token. Requires "Grant resource - Write" API permission.

POST /admin/v1/tokens

Parameters

Response Codes

Response Format

Returns the created single token object. Refer to Retrieve Hardware Tokens for an explanation of the object's keys.

Example Response

{
  "stat": "OK",
  "response": {
    "admins": [],
    "serial": "123456",
    "token_id": "DH6G5OP9NU4C5UP00LMN",
    "totp_step": null,
    "type": "h6",
    "users": []
  }
}

Retrieve Hardware Token by ID

Return the single hardware token with token_id. Requires "Grant resource - Read" or "Grant resource - Write" API permission.

GET /admin/v1/tokens/[token_id]

Parameters

This API endpoint has no parameters.

Response Codes

Response Format

Returns a single user object. Refer to Retrieve Hardware Tokens for an explanation of the object's keys.

Example Response

{
  "stat": "OK",
  "response": {
    "admins": [
      {
      "admin_id": "DESMP00LIAKRJPD4DZSH",
      "created": 1648143942,
      "email": "jsmith@example.com",
      "last_login": 1343921403,
      "name": "Joe Smith"
      }
    ],
    "serial": "123456",
    "token_id": "DHIZ34ALBA2445ND4AI2",
    "totp_step": null,
    "type": "d1",
    "users": [
      {
      "alias1": "joe.smith",
      "alias2": "jsmith@example.com",
      "alias3": null,
      "alias4": null,
      "aliases": {
          "alias1": "joe.smith",
          "alias2": "jsmith@example.com"
      },
      "created": 1343621411,
      "email": "jsmith@example.com",
      "enable_auto_prompt": true,
      "firstname": "",
      "is_enrolled": true,
      "last_directory_sync": null,
      "last_login": 1343921403,
      "lastname": "",
      "notes": "",
      "realname": "Joe Smith",
      "status": "active",
      "user_id": "DUJZ2U4L80HT45MQ4EOQ",
      "username": "jsmith"
      }
    ]
  }
}

Resync Hardware Token

Resynchronize the hardware token with ID token_id by providing three successive codes from the token. Only HOTP and Duo-D100 tokens can be resynchronized. YubiKey tokens operating in their native AES mode do not need resynchronization. Requires "Grant resource - Write" API permission.

POST /admin/v1/tokens/[token_id]/resync

Parameters

Response Codes

Response Format

Empty string.

Example Response

{
  "stat": "OK",
  "response": ""
}

Delete Hardware Token

Delete the hardware token with ID token_id from the system. Requires "Grant resource - Write" API permission.

DELETE /admin/v1/tokens/[token_id]

Parameters

This API endpoint has no parameters.

Response Codes

Response Format

Empty string.

Example Response

{
  "stat": "OK",
  "response": ""
}

U2F Tokens

The U2F Tokens API endpoint /admin/v1/u2ftokens is deprecated as of February 2022. This API no longer allows listing all U2F tokens or deletion of U2F tokens. Requests to this endpoint now fail with the following response:

{
  "stat": "FAIL",
  "code": 40301,
  "message": "Access forbidden",
}

Per-user U2F Token Operations

See Retrieve U2F Tokens by User ID.

WebAuthn Credentials

Per-user WebAuthn Credential Operations

See Retrieve WebAuthn Credentials by User ID.

Retrieve WebAuthn Credentials

Returns a paged list of all registered WebAuthn credentials. To fetch all results, call repeatedly with the offset parameter as long as the result metadata has a next_offset value. Requires "Grant resource - Read" API permission to retrieve user credentials, and "Grant administrators - Read" or "Grant administrators - Write" API permission to retrieve administrator credentials.

GET /admin/v1/webauthncredentials

Parameters

Use the paging parameters to change the number of results shown in a response or to retrieve additional results. See Response Paging for details.

This API endpoint has no additional parameters.

Response Codes

Response Format

Example Response

{
  "stat": "OK",
  "response": [
    {
        "aaguid": "abcdefgh-123i-4jkl-5mno-6p789012q3rs",
        "admin": null,
        "backup_eligible": true,
        "backup_status": true,
        "credential_id": "A1bCd34efgH5I6jK6lmnoPQrS78",
        "credential_name": "Touch ID",
        "date_added": 1707422111,
        "label": "iCloud Keychain",
        "passwordless_authorized": true,
        "registered_as": "platform",
        "transports": ["hybrid", "internal"],
        "user": {
            "alias1": joesmith,
            "alias2": null,
            "alias3": null,
            "alias4": null,
            "aliases": {},
            "created": 1677007225,
            "email": "",
            "enable_auto_prompt": true,
            "firstname": "",
            "is_enrolled": true,
            "last_directory_sync": null,
            "last_login": 1677007248,
            "lastname": "",
            "notes": "",
            "realname": "",
            "status": "active",
            "user_id": "DUDKPMBF009AHLHNDPDY",
            "username": "jsmith"
        },
        "uv_capable": true,
        "webauthnkey": "WAVTE9JYG4VSQU9LT1B4"
    },
    {
        "aaguid": "abcdefgh-123i-4jkl-5mno-6p789012q3rs",
        "admin": {
            "admin_id": "DEBMWJ05HTBZBU6LNCF3",
            "created": null,
            "email": "ellery.munson@example.com",
            "last_login": 1679420096,
            "name": "Ellery Munson"
        },
        "backup_eligible": false,
        "backup_status": false,
        "credential_id": "A1bCd3_Yx7Xy8Oj_uxJKODn3WFPH7Ml4wqqLIKj5ro",
        "credential_name": "Security key",
        "date_added": 1679413709,
        "date_last_used": 1706714235,
        "label": "Security key",
        "passwordless_authorized": false,
        "registered_as": "unknown",
        "transports": ["usb"],
        "user": null,
        "uv_capable": false,
        "webauthnkey": "WARRM3HNRDFF3L3AQLXW"
    },
  ]
}

Retrieve WebAuthn Credentials by Key

Return the single WebAuthn credential with webauthnkey. Requires "Grant resource - Read" API permission to retrieve a user's credential, and "Grant administrators - Read" or "Grant administrators - Write" API permission to retrieve an administrator's credential.

GET /admin/v1/webauthncredentials/[webauthnkey]

Parameters

This API endpoint has no parameters.

Response Codes

Response Format

Returns a single WebAuthn credential object. Refer to Retrieve WebAuthn Credentials for an explanation of the object's keys.

Example Response

{
  "stat": "OK",
  "response": {
      "aaguid": "abcdefgh-123i-4jkl-5mno-6p789012q3rs",
      "admin": null,
      "backup_eligible": true,
      "backup_status": true,
      "credential_id": "A1bCd34efgH5I6jK6lmnoPQrS78",
      "credential_name": "Touch ID",
      "date_added": 1707422111,
      "label": "iCloud Keychain",
      "passwordless_authorized": true,
      "registered_as": "platform",
      "transports": ["hybrid", "internal"],
      "user": {
          "alias1": joesmith,
          "alias2": null,
          "alias3": null,
          "alias4": null,
          "aliases": {},
          "created": 1677007225,
          "email": "",
          "enable_auto_prompt": true,
          "firstname": "",
          "is_enrolled": true,
          "last_directory_sync": null,
          "last_login": 1677007248,
          "lastname": "",
          "notes": "",
          "realname": "",
          "status": "active",
          "user_id": "DUDKPMBF009AHLHNDPDY",
          "username": "jsmith"
      },
      "uv_capable": true,
      "webauthnkey": "WAVTE9JYG4VSQU9LT1B4"
  }
}

Delete WebAuthn Credential

Delete the WebAuthn credential with key webauthnkey from the system. Requires "Grant resource - Write" API permission to delete a credential from a user, and "Grant administrators - Write" API permission to delete a credential from an administrator.

DELETE /admin/v1/webauthncredentials/[webauthnkey]

Parameters

This API endpoint has no parameters.

Response Codes

Response Format

Empty string.

Example Response

{
  "stat": "OK",
  "response": ""
}

Desktop Authenticators

Per-user Desktop Authenticators Operations

See Retrieve Desktop Authenticators by User ID.

Retrieve Desktop Authenticators

Returns a paged list of desktop authenticators. To fetch all results, call repeatedly with the offset parameter as long as the result metadata has a next_offset. Requires "Grant resource - Read" API permission.

GET /admin/v1/desktop_authenticators

Parameters

Use the paging parameters to change the number of results shown in a response or to retrieve additional results. See Response Paging for details.

This API endpoint has no additional parameters.

Response Codes

Response Format

Example Response

{
  "response": [
    {
      "daid": 123,
      "dakey": "DDABCDE1FGHIJ23KL4M",
      "device_name": "RSANCHEZ-M-A12B",
      "duo_desktop_version": "6.12.0.0",
      "os_family": "Mac OS X",
      "user": {
        "alias1": null,
        "alias2": null,
        "alias3": null,
        "alias4": null,
        "aliases": {},
        "created": 1721156264,
        "email": "",
        "enable_auto_prompt": true,
        "firstname": "",
        "is_enrolled": true,
        "last_directory_sync": null,
        "last_login": 1721245422,
        "lastname": "",
        "notes": "",
        "realname": "",
        "status": "active",
        "user_id": "DABCDEFGHIJKL1MNOPQR",
        "username": "rsanchez"
      }
    },
    {
      "daid": 234,
      "dakey": "DDABCDE1FGHIJ23KL45",
      "device_name": "DESKTOP-ABC1234",
      "duo_desktop_version": "6.12.0",
      "os_family": "Windows",
      "user": {
        "alias1": null,
        "alias2": null,
        "alias3": null,
        "alias4": null,
        "aliases": {},
        "created": 1721156264,
        "email": "",
        "enable_auto_prompt": true,
        "firstname": "",
        "is_enrolled": true,
        "last_directory_sync": null,
        "last_login": 1721245422,
        "lastname": "",
        "notes": "",
        "realname": "",
        "status": "active",
        "user_id": "DABCDEFGHIJKL2MNOPQR",
        "username": "avandalay"
      }
    }
  ],
  "stat": "OK"
}

Retrieve Desktop Authenticator by Key

Return the single desktop authenticator with dakey. Requires "Grant resource - Read" API permission.

GET /admin/v1/desktop_authenticators/[dakey]

Parameters

This API endpoint has no parameters.

Response Codes

Response Format

Returns a single desktop authenticator object. Refer to Retrieve Desktop Authenticators for an explanation of the object's keys.

Example Response

{
  "response": {
    "daid": 123,
    "dakey": "DDABCDE1FGHIJ23KL4M",
    "device_name": "RSANCHEZ-M-A12B",
    "duo_desktop_version": "6.12.0.0",
    "os_family": "Mac OS X",
    "user": {
      "alias1": null,
      "alias2": null,
      "alias3": null,
      "alias4": null,
      "aliases": {},
      "created": 1721156264,
      "email": "",
      "enable_auto_prompt": true,
      "firstname": "",
      "is_enrolled": true,
      "last_directory_sync": null,
      "last_login": 1721245422,
      "lastname": "",
      "notes": "",
      "realname": "",
      "status": "active",
      "user_id": "DABCDEFGHIJKL1MNOPQR",
      "username": "rsanchez"
    }
  }
  "stat": "OK"
}

Delete Desktop Authenticator

Delete the desktop authenticator with key dakey from the system. Requires "Grant resource - Write" API permission to delete a desktop authenticator from a user.

DELETE /admin/v1/desktop_authenticators/[dakey]

Parameters

This API endpoint has no parameters.

Response Codes

Response Format

Empty string.

Example Response

{
  "response": "",
  "stat": "OK",
}

Shared Device Authentication

Retrieve Shared Device Authentication Configurations

Returns Shared Device Authentication configurations. To fetch all results, call repeatedly with the offset parameter as long as the result metadata has a next_offset. Requires "Grant resource - Read" API permissions.

GET /admin/v1/desktop_authenticators/shared_device_auth

Parameters

Use the paging parameters to change the number of results shown in a response or to retrieve additional results. See Response Paging for details.

This API endpoint has no additional parameters.

Response Codes

Response Format

Example Response

{
  "metadata": {
    "total_objects": 2
  },
  "response": [
    {
      "active": true,
      "created": "2024-09-03 14:20:52",
      "groups": [
        {
          "desc": "",
          "group_id": "DGABCDE1FGHI2345JKLM",
          "name": "NetAdmins",
          "status": "Active"
        },
        {
          "desc": "",
          "group_id": "DGABCDE1FGHI2345JKL6",
          "name": "Contractors",
          "status": "Active"
        }
      ],
      "shared_device_key": "DDAB1CDEFGHI2JKLMNO",
      "name": "Help Center 1",
      "trusted_endpoint_integrations": [
        {
          "name": "Generic with Duo Desktop",
          "trusted_endpoint_integration_id": "DMAB1CDEF2G34H5IJKLM"
        },
        {
          "name": "Meraki with Duo Desktop",
          "trusted_endpoint_integration_id": "DMAB1CDEF2G34H5IJKL6"
        }
      ]
    },
    {
      "active": false,
      "created": "2024-09-02 14:20:52",
      "groups": [
        {
          "desc": "",
          "group_id": "DGABCDE1FGHI2345JKL6",
          "name": "Help Desk",
          "status": "Active"
        }
      ],
      "shared_device_key": "DDAB1CDEFGHI2JKLMN3",
      "name": "Help Center 2",
      "trusted_endpoint_integrations": [
        {
          "name": "Manual with Duo Desktop",
          "trusted_endpoint_integration_id": "DMAB1CDEF2G34H5IJKL6"
        }
      ]
    }
  ],
  "stat": "OK"
}

Retrieve Shared Device Authentication Configuration by Key

Returns a single Shared Device Authentication configuration with shared_device_key. Requires "Grant resource - Read" API permissions.

GET /admin/v1/desktop_authenticators/shared_device_auth/[shared_device_key]

Parameters

This API endpoint has no parameters.

Response Codes

Response Format

Returns a single shared device authentication configuration. Refer to Retrieve Shared Device Authentication Configurations for an explanation of the object's keys.

Example Response

{
  "response": [
    {
      "active": true,
      "created": "2024-09-03 14:20:52",
      "groups": [
        {
          "desc": "",
          "group_id": "DGABCDE1FGHI2345JKLM",
          "name": "NetAdmins",
          "status": "Active"
        },
        {
          "desc": "",
          "group_id": "DGABCDE1FGHI2345JKL6",
          "name": "Contractors",
          "status": "Active"
        }
      ],
      "shared_device_key": "DDAB1CDEFGHI2JKLMNO",
      "name": "Help Center 1",
      "trusted_endpoint_integrations": [
        {
          "name": "Generic with Duo Desktop",
          "trusted_endpoint_integration_id": "DMAB1CDEF2G34H5IJKLM"
        },
        {
          "name": "Meraki with Duo Desktop",
          "trusted_endpoint_integration_id": "DMAB1CDEF2G34H5IJKL6"
        }
      ]
    }
  ],
  "stat": "OK"
}

Create Shared Device Authentication Configuration

Create a new shared device authentication configuration with specified management integrations and user groups. Requires "Grant resource - Write" API permission.

POST /admin/v1/desktop_authenticators/shared_device_auth

Parameters

Response Codes

Response Format

Returns the new shared device authentication configuration created. Refer to Retrieve Shared Device Authentication Configurations for an explanation of the object's keys.

Example Response

{
  "response": [
    {
      "active": true,
      "created": "2024-09-03 14:20:52",
      "groups": [
        {
          "desc": "",
          "group_id": "DGABCDE1FGHI2345JKLM",
          "name": "NetAdmins",
          "status": "Active"
        },
        {
          "desc": "",
          "group_id": "DGABCDE1FGHI2345JKL6",
          "name": "Contractors",
          "status": "Active"
        }
      ],
      "shared_device_key": "DDAB1CDEFGHI2JKLMNO",
      "name": "Help Center 1",
      "trusted_endpoint_integrations": [
        {
          "name": "Generic with Duo Desktop",
          "trusted_endpoint_integration_id": "DMAB1CDEF2G34H5IJKLM"
        },
        {
          "name": "Meraki with Duo Desktop",
          "trusted_endpoint_integration_id": "DMAB1CDEF2G34H5IJKL6"
        }
      ]
    }
  ],
  "stat": "OK"
}

Update Shared Device Authentication Configuration

Update a shared device authentication configuration with a specified shared_device_key. Requires "Grant resource - Write" API permission.

Note: This API call uses the PUT request method, which must be represented as JSON and cannot be passed in via URL parameters. Some Duo clients (Python or Java, for example) offer helper functions to handle requests to the Admin API.

PUT /admin/v1/desktop_authenticators/shared_device_auth/[shared_device_key]

Parameters

Response Codes

Response Format

Returns the updated shared device authentication configuration. Refer to Retrieve Shared Device Authentication Configurations for an explanation of the object's keys.

Example Response

{
  "response": [
    {
      "active": true,
      "created": "2024-09-03 14:20:52",
      "groups": [
        {
          "desc": "",
          "group_id": "DGABCDE1FGHI2345JKLM",
          "name": "NetAdmins",
          "status": "Active"
        },
        {
          "desc": "",
          "group_id": "DGABCDE1FGHI2345JKL6",
          "name": "Contractors",
          "status": "Active"
        }
      ],
      "shared_device_key": "DDAB1CDEFGHI2JKLMNO",
      "name": "Help Center 1",
      "trusted_endpoint_integrations": [
        {
          "name": "Generic with Duo Desktop",
          "trusted_endpoint_integration_id": "DMAB1CDEF2G34H5IJKLM"
        },
        {
          "name": "Meraki with Duo Desktop",
          "trusted_endpoint_integration_id": "DMAB1CDEF2G34H5IJKL6"
        }
      ]
    }
  ],
  "stat": "OK"
}

Delete Shared Device Authentication Configuration

Delete a shared device authentication configuration with a specified shared_device_key. Requires "Grant resource - Write" API permission.

DELETE /admin/v1/desktop_authenticators/shared_device_auth/[shared_device_key]

Parameters

This API endpoint has no parameters.

Response Codes

Response Format

Empty string.

Example Response

{
  "response": "",
  "stat": "OK"
}

Bypass Codes

Per-user Bypass Code Operations

See Create Bypass Codes for User and Retrieve Bypass Codes by User ID.

Retrieve Bypass Codes

Returns a paged list of information about all bypass codes. To fetch all results, call repeatedly with the offset parameter as long as the result metadata has a next_offset value. Output does not include the actual bypass codes. Requires "Grant resource - Read" API permission.

GET /admin/v1/bypass_codes

Parameters

Use the paging parameters to change the number of results shown in a response or to retrieve additional results. See Response Paging for details.

This API endpoint has no additional parameters.

Response Codes

Response Format

Example Response

{
  "stat": "OK",
  "response": [
    {
    "admin_email": "janesmith@example.com",
    "bypass_code_id": "DB2A9F0012RL54001FA3",
    "created": 1522260759,
    "expiration": 1522264359,
    "reuse_count": 1,
    "user": {
      "alias1": "joe.smith",
      "alias2": "jsmith@example.com",
      "alias3": null,
      "alias4": null,
      "aliases": {
        "alias1": "joe.smith",
        "alias2": "jsmith@example.com"
      },
      "created": 1384275337,
      "email": "jsmith@example.com",
      "enable_auto_prompt": true,
      "external_id": "1a2345b6-7cd8-9e0f-g1hi-23j45kl6m789",
      "firstname": "",
      "is_enrolled": true,
      "last_directory_sync": 1384275337,
      "last_login": 1514922986,
      "lastname": "",
      "notes": "",
      "realname": "Joe Smith",
      "status": "active",
      "user_id": "DU3RP9I2WOC59VZX672N",
      "username": "jsmith"
    }
  ]
}

Retrieve Bypass Code by ID

Return information about a single bypass code with bypass_code_id. Output does not include the actual bypass code. Requires "Grant resource - Read" API permission.

GET /admin/v1/bypass_codes/[bypass_code_id]

Parameters

This API endpoint has no parameters.

Response Codes

Response Format

Returns a single bypass code object. Refer to Retrieve Bypass Codes for an explanation of the object's keys.

Example Response

{
  "stat": "OK",
  "response": {
    "admin_email": "janesmith@example.com",
    "bypass_code_id": "DB2A9F0012RL54001FA3",
    "created": 1522260759,
    "expiration": 1522264359,
    "reuse_count": 1,
    "user": {
      "alias1": "joe.smith",
      "alias2": "jsmith@example.com",
      "alias3": null,
      "alias4": null,
      "aliases": {
        "alias1": "joe.smith",
        "alias2": "jsmith@example.com"
      },
      "created": 1384275337,
      "email": "jsmith@example.com",
      "enable_auto_prompt": true,
      "external_id": "1a2345b6-7cd8-9e0f-g1hi-23j45kl6m789",
      "firstname": "",
      "is_enrolled": true,
      "last_directory_sync": 1384275337,
      "last_login": 1514922986,
      "lastname": "",
      "notes": "",
      "realname": "Joe Smith",
      "status": "active",
      "user_id": "DU3RP9I2WOC59VZX672N",
      "username": "jsmith"
    }
  }
}

Delete Bypass Code

Delete the bypass code with ID bypass_code_id from the system. Requires "Grant resource - Write" API permission.

DELETE /admin/v1/bypass_codes/[bypass_code_id]

Parameters

This API endpoint has no parameters.

Response Codes

Response Format

Empty string.

Example Response

{
  "stat": "OK",
  "response": ""
}

Integrations

The Integrations v3 API does not use the same authentication and request signing detailed earlier in this document. Our Python, Go, Java, and Node.JS API clients have been updated with the new authentication and signing requirements and include support for the Integrations v2 API endpoints. We recommend you use the duo_client_python Python API client, the duo_api_golang Go API client, the duo_client_java Java API client, or the duo_api_nodejs Node.JS API client to interact with the Integrations v2 endpoints.

Retrieve Integrations

Returns a paged list of integrations. To fetch all results, call repeatedly with the offset parameter as long as the result metadata has a next_offset value. Requires "Grant resource - Read" API permission.

GET /admin/v3/integrations

Parameters

Use the paging parameters to change the number of results shown in a response or to retrieve additional results. See Response Paging for details.

Response Codes

Response Format

Example Response

{
  "stat": "OK",
  "response": [
    {
      "adminapi_admins": 0,
      "adminapi_admins_read": 0,
      "adminapi_allow_to_set_permissions": 0,
      "adminapi_info": 0,
      "adminapi_integrations": 0,
      "adminapi_read_log": 0,
      "adminapi_read_resource": 0,
      "adminapi_settings": 0,
      "adminapi_write_resource": 0,
      "enroll_policy": "",
      "frameless_auth_prompt_enabled": 1,
      "greeting": "Welcome to Duo.",
      "groups_allowed": [],
      "integration_key": "DIRWIH0ZZPV4G88B37VQ",
      "ip_whitelist": [],
      "ip_whitelist_enroll_policy": "",
      "missing_web_referer_policy": "deny",
      "name": "Generic SAML Service Provider",
      "notes": "",
      "policy_key": "POHSLA8SP00LABDAD98Y",
      "prompt_v4_enabled": 1,
      "secret_key": "************************************HazY7",
      "self_service_allowed": false,
      "sso": {
          "idp_metadata": {
            "cert": "-----BEGIN CERTIFICATE-----MIIDDTCCAfW...gAwIBAgIUAdARSAE-----END CERTIFICATE-----\n",
            "entity_id": "https://sso-abc1def2.sso.duosecurity.com/saml2/idp/RI6WF1LHX9N8GBOEPGZR/metadata",
            "metadata_url": "https://sso-abc1def2.sso.duosecurity.com/saml2/idp/RI6WF1LHX9N8GBOEPGZR/metadata",
            "slo_url": "https://sso-abc1def2.sso.duosecurity.com/saml2/idp/RI6WF1LHX9N8GBOEPGZR/slo",
            "sso_url": "https://sso-abc1def2.sso.duosecurity.com/saml2/idp/RI6WF1LHX9N8GBOEPGZR/sso"
          },
          "saml_config": {
            "acs_urls": [],
            "assertion_encryption_algorithm": null,
            "attribute_transformations": [],
            "encrypt_assertion": false,
            "entity_id": "",
            "key_transport_encryption_algorithm": null,
            "mapped_attrs": {},
            "nameid_attribute": "",
            "nameid_format": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified",
            "relaystate": null,
            "remote_cert": null,
            "role_attrs": {},
            "sign_assertion": true,
            "sign_response": true,
            "signing_algorithm": "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256",
            "slo_url": "",
            "spinitiated_url": null,
            "static_attrs": null
          }
      },
      "trusted_device_days": 0,
      "type": "websdk",
      "user_access": "NO_USERS",
      "username_normalization_policy": "None",
      "web_referers_enabled": 0
    },
    {
      "adminapi_admins": 0,
      "adminapi_admins_read": 0,
      "adminapi_allow_to_set_permissions": 0,
      "adminapi_info": 0,
      "adminapi_integrations": 0,
      "adminapi_read_log": 1,
      "adminapi_read_resource": 0,
      "adminapi_settings": 0,
      "adminapi_write_resource": 0,
      "enroll_policy": "",
      "greeting": "Welcome to Duo.",
      "groups_allowed": [],
      "integration_key": "DIRWIH0ZZPV4GJ05H7VQ",
      "name": "Admin API",
      "networks_for_api_access": "",
      "notes": "",
      "secret_key": "************************************HazY7",
      "self_service_allowed": false,
      "type": "adminapi",
      "user_access": "ALL_USERS",
      "username_normalization_policy": "None",
    }
  ]
}

Create Integration

Create a new integration. The new integration key and secret key are randomly generated and returned in the response. This endpoint cannot create non-generic Duo Single Sign-On applications. Requires "Grant applications" API permission.

Note: This API call uses POST data, which must be represented as JSON and cannot be passed in via URL parameters. Some Duo clients (Python or Java, for example) offer helper functions to handle requests to the Admin API.

POST /admin/v3/integrations

Parameters

Response Codes

Response Format

Returns the created single integration object. Refer to Retrieve Integrations for an explanation of the object's keys.

Example Response

Same as Retrieve Integration by Integration Key.

Retrieve Integration by Integration Key

Return the single integration with integration_key. Requires "Grant applications" API permission.

GET /admin/v3/integrations/[integration_key]

Parameters

This API endpoint has no parameters.

Response Codes

Response Format

Returns the single integration object. Refer to Retrieve Integrations for an explanation of the object's keys.

Example Response

{
  "stat": "OK",
  "response": {
      "adminapi_admins": 0,
      "adminapi_admins_read": 0,
      "adminapi_allow_to_set_permissions": 0,
      "adminapi_info": 0,
      "adminapi_integrations": 0,
      "adminapi_read_log": 0,
      "adminapi_read_resource": 0,
      "adminapi_settings": 0,
      "adminapi_write_resource": 0,
      "enroll_policy": "",
      "frameless_auth_prompt_enabled": 1,
      "greeting": "Welcome to Duo.",
      "groups_allowed": [],
      "integration_key": "DIRWIH0ZZPV4G88B37VQ",
      "ip_whitelist": [],
      "ip_whitelist_enroll_policy": "",
      "missing_web_referer_policy": "deny",
      "name": "Generic SAML Service Provider",
      "notes": "",
      "policy_key": "POHSLA8SP00LABDAD98Y",
      "prompt_v4_enabled": 1,
      "secret_key": "************************************HazY7",
      "self_service_allowed": false,
      "sso": {
          "idp_metadata": {
            "cert": "-----BEGIN CERTIFICATE-----MIIDDTCCAfW...gAwIBAgIUAdARSAE-----END CERTIFICATE-----\n",
            "entity_id": "https://sso-abc1def2.sso.duosecurity.com/saml2/idp/RI6WF1LHX9N8GBOEPGZR/metadata",
            "metadata_url": "https://sso-abc1def2.sso.duosecurity.com/saml2/idp/RI6WF1LHX9N8GBOEPGZR/metadata",
            "slo_url": "https://sso-abc1def2.sso.duosecurity.com/saml2/idp/RI6WF1LHX9N8GBOEPGZR/slo",
            "sso_url": "https://sso-abc1def2.sso.duosecurity.com/saml2/idp/RI6WF1LHX9N8GBOEPGZR/sso"
          },
          "saml_config": {
            "acs_urls": [],
            "assertion_encryption_algorithm": null,
            "attribute_transformations": [],
            "encrypt_assertion": false,
            "entity_id": "",
            "key_transport_encryption_algorithm": null,
            "mapped_attrs": {},
            "nameid_attribute": "",
            "nameid_format": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified",
            "relaystate": null,
            "remote_cert": null,
            "role_attrs": {},
            "sign_assertion": true,
            "sign_response": true,
            "signing_algorithm": "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256",
            "slo_url": "",
            "spinitiated_url": null,
            "static_attrs": null
          }
      },
      "trusted_device_days": 0,
      "type": "websdk",
      "user_access": "NO_USERS",
      "username_normalization_policy": "None",
      "web_referers_enabled": 0
  }
}

Modify Integration

Change the name, greeting, and/or notes of the integration with integration key integration_key, or reset its secret key. When modifying an Admin API integration permissions can also be added or removed. This endpoint cannot modify non-generic Duo Single Sign-On applications. Requires "Grant applications" API permission.

Note: This API call uses POST data, which must be represented as JSON and cannot be passed in via URL parameters. Some Duo clients (Python or Java, for example) offer helper functions to handle requests to the Admin API.

POST /admin/v3/integrations/[integration_key]

Parameters

Response Codes

Response Format

Returns the modified single integration object. Refer to Retrieve Integrations for an explanation of the object's keys.

Example Response

Same as Retrieve Integration by Integration Key.

Delete Integration

Delete the integration with integration_key from the system. Attempting to delete the Admin API integration whose secret key is used to sign this request will return an error. This endpoint cannot delete non-generic Duo Single Sign-On applications. Requires "Grant applications" API permission.

DELETE /admin/v3/integrations/[integration_key]

Parameters

This API endpoint has no parameters.

Response Codes

Response Format

Empty string.

Example Response

{
  "stat": "OK",
  "response": ""
}

Retrieve Secret Key

Retrieve the skey for the specified integration. Requires "Grant applications" API permission. Does not work for SSO integrations.

This endpoint does not use the same authentication and request signing detailed earlier in this document. Our Python, Go, Java, and Node.JS API clients have been updated with the new authentication and signing requirements and include support for this endpoint operation. We recommend you use the duo_client_python Python API client, the duo_api_golang Go API client, the duo_client_java Java API client, or the duo_api_nodejs Node.JS API client to perform this operation.

GET /admin/v1/integrations/[integration_key]/skey

Parameters

This API endpoint has no parameters.

Response Codes

Response Format

Returns the skey.

Example Response

{
  "response": {
    "skey": "Zh5eGmUq9zpfQnyUIu5OL9iWoMMv5ZNmk3zLJ4Ep"
  },
  "stat": "OK"
}

Retrieve Client Secret for an OAuth Integration

Retrieve the client_secret for the specified OAuth integration. Requires "Grant applications" API permission.

GET /admin/v3/integrations/oauth_cc/[integration_key]/client_secret/[client_id]

Parameters

This API endpoint has no parameters.

Response Codes

Response Format

Returns the client_secret.

Example Response

{
  "response": {
    "client_secret": "Zh5eGmUq9zpfQnyUIu5OL9iWoMMv5ZNmk3zLJ4Ep"
  },
  "stat": "OK"
}

Reset Client Secret for an OAuth Integration

Reset the client_secret for the specified OAuth integration. Requires "Grant applications" API permission.

POST /admin/v3/integrations/oauth_cc/[integration_key]/client_secret/[client_id]

Parameters

This API endpoint has no parameters.

Response Codes

Response Format

Empty string.

Example Response

{
  "response": {},
  "stat": "OK"
}

Retrieve Client Secret for an OIDC Integration

Retrieve the client_secret for the specified OIDC integration. Requires "Grant applications" API permission.

GET /admin/v3/integrations/oidc/[integration_key]/client_secret

Parameters

This API endpoint has no parameters.

Response Codes

Response Format

Returns the client_secret.

Example Response

{
  "response": {
    "client_secret": "Zh5eGmUq9zpfQnyUIu5OL9iWoMMv5ZNmk3zLJ4Ep"
  },
  "stat": "OK"
}

Reset Client Secret for an OIDC Integration

Reset the client_secret for the specified OIDC integration. Requires "Grant applications" API permission.

POST /admin/v3/integrations/oidc/[integration_key]/client_secret

Parameters

This API endpoint has no parameters.

Response Codes

Response Format

Empty string.

Example Response

{
  "response": {},
  "stat": "OK"
}

SSO Parameters

OAuth Parameters

OIDC Parameters

SAML Parameters

Integrations (Legacy v2)

The Integrations v2 API does not use the same authentication and request signing detailed earlier in this document. Our Python, Go, Java, and Node.JS API clients have been updated with the new authentication and signing requirements and include support for the Integrations v2 API endpoints. We recommend you use the duo_client_python Python API client, the duo_api_golang Go API client, the duo_client_java Java API client, or the duo_api_nodejs Node.JS API client to interact with the Integrations v2 endpoints.

Retrieve Integrations (Legacy v2)

Returns a paged list of integrations. To fetch all results, call repeatedly with the offset parameter as long as the result metadata has a next_offset value. Requires "Grant resource - Read" API permission.

GET /admin/v2/integrations

Parameters

Use the paging parameters to change the number of results shown in a response or to retrieve additional results. See Response Paging for details.

Response Codes

Response Format

Example Response

{
  "stat": "OK",
  "response": [
    {
      "adminapi_admins": 0,
      "adminapi_admins_read": 0,
      "adminapi_allow_to_set_permissions": 0,
      "adminapi_info": 0,
      "adminapi_integrations": 0,
      "adminapi_read_log": 0,
      "adminapi_read_resource": 0,
      "adminapi_settings": 0,
      "adminapi_write_resource": 0,
      "enroll_policy": "",
      "frameless_auth_prompt_enabled": 1,
      "greeting": "Welcome to Duo.",
      "groups_allowed": [],
      "integration_key": "DIRWIH0ZZPV4G88B37VQ",
      "ip_whitelist": [],
      "ip_whitelist_enroll_policy": "",
      "missing_web_referer_policy": "deny",
      "name": "Generic SAML Service Provider",
      "notes": "",
      "policy_key": "POHSLA8SP00LABDAD98Y",
      "prompt_v4_enabled": 1,
      "secret_key": "************************************HazY7",
      "self_service_allowed": false,
      "sso": {
          "idp_metadata": {
            "cert": "-----BEGIN CERTIFICATE-----MIIDDTCCAfW...gAwIBAgIUAdARSAE-----END CERTIFICATE-----\n",
            "entity_id": "https://sso-abc1def2.sso.duosecurity.com/saml2/idp/RI6WF1LHX9N8GBOEPGZR/metadata",
            "metadata_url": "https://sso-abc1def2.sso.duosecurity.com/saml2/idp/RI6WF1LHX9N8GBOEPGZR/metadata",
            "slo_url": "https://sso-abc1def2.sso.duosecurity.com/saml2/idp/RI6WF1LHX9N8GBOEPGZR/slo",
            "sso_url": "https://sso-abc1def2.sso.duosecurity.com/saml2/idp/RI6WF1LHX9N8GBOEPGZR/sso"
          },
          "saml_config": {
            "acs_urls": [],
            "assertion_encryption_algorithm": null,
            "attribute_transformations": [],
            "encrypt_assertion": false,
            "entity_id": "",
            "key_transport_encryption_algorithm": null,
            "mapped_attrs": {},
            "nameid_attribute": "",
            "nameid_format": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified",
            "relaystate": null,
            "remote_cert": null,
            "role_attrs": {},
            "sign_assertion": true,
            "sign_response": true,
            "signing_algorithm": "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256",
            "slo_url": "",
            "spinitiated_url": null,
            "static_attrs": null
          }
      },
      "trusted_device_days": 0,
      "type": "websdk",
      "username_normalization_policy": "None",
      "web_referers_enabled": 0
    },
    {
      "adminapi_admins": 0,
      "adminapi_admins_read": 0,
      "adminapi_allow_to_set_permissions": 0,
      "adminapi_info": 0,
      "adminapi_integrations": 0,
      "adminapi_read_log": 1,
      "adminapi_read_resource": 0,
      "adminapi_settings": 0,
      "adminapi_write_resource": 0,
      "enroll_policy": "",
      "greeting": "Welcome to Duo.",
      "groups_allowed": [],
      "integration_key": "DIRWIH0ZZPV4GJ05H7VQ",
      "name": "Admin API",
      "networks_for_api_access": "",
      "notes": "",
      "secret_key": "************************************HazY7",
      "self_service_allowed": false,
      "type": "adminapi",
      "username_normalization_policy": "None",
    }
  ]
}

Create Integration (Legacy v2)

Create a new integration. The new integration key and secret key are randomly generated and returned in the response. Requires "Grant applications" API permission.

Note: This API call uses POST data, which must be represented as JSON and cannot be passed in via URL parameters. Some Duo clients (Python or Java, for example) offer helper functions to handle requests to the Admin API.

POST /admin/v2/integrations

Parameters

Response Codes

Response Format

Returns the created single integration object. Refer to Retrieve Integrations for an explanation of the object's keys.

Example Response

Same as Retrieve Integration by Integration Key.

Retrieve Integration by Integration Key (Legacy v2)

Return the single integration with integration_key. Requires "Grant applications" API permission.

GET /admin/v2/integrations/[integration_key]

Parameters

This API endpoint has no parameters.

Response Codes

Response Format

Returns the single integration object. Refer to Retrieve Integrations for an explanation of the object's keys.

Example Response

{
  "stat": "OK",
  "response": {
      "adminapi_admins": 0,
      "adminapi_admins_read": 0,
      "adminapi_allow_to_set_permissions": 0,
      "adminapi_info": 0,
      "adminapi_integrations": 0,
      "adminapi_read_log": 0,
      "adminapi_read_resource": 0,
      "adminapi_settings": 0,
      "adminapi_write_resource": 0,
      "enroll_policy": "",
      "frameless_auth_prompt_enabled": 1,
      "greeting": "Welcome to Duo.",
      "groups_allowed": [],
      "integration_key": "DIRWIH0ZZPV4G88B37VQ",
      "ip_whitelist": [],
      "ip_whitelist_enroll_policy": "",
      "missing_web_referer_policy": "deny",
      "name": "Generic SAML Service Provider",
      "notes": "",
      "policy_key": "POHSLA8SP00LABDAD98Y",
      "prompt_v4_enabled": 1,
      "secret_key": "************************************HazY7",
      "self_service_allowed": false,
      "sso": {
          "idp_metadata": {
            "cert": "-----BEGIN CERTIFICATE-----MIIDDTCCAfW...gAwIBAgIUAdARSAE-----END CERTIFICATE-----\n",
            "entity_id": "https://sso-abc1def2.sso.duosecurity.com/saml2/idp/RI6WF1LHX9N8GBOEPGZR/metadata",
            "metadata_url": "https://sso-abc1def2.sso.duosecurity.com/saml2/idp/RI6WF1LHX9N8GBOEPGZR/metadata",
            "slo_url": "https://sso-abc1def2.sso.duosecurity.com/saml2/idp/RI6WF1LHX9N8GBOEPGZR/slo",
            "sso_url": "https://sso-abc1def2.sso.duosecurity.com/saml2/idp/RI6WF1LHX9N8GBOEPGZR/sso"
          },
          "saml_config": {
            "acs_urls": [],
            "assertion_encryption_algorithm": null,
            "attribute_transformations": [],
            "encrypt_assertion": false,
            "entity_id": "",
            "key_transport_encryption_algorithm": null,
            "mapped_attrs": {},
            "nameid_attribute": "",
            "nameid_format": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified",
            "relaystate": null,
            "remote_cert": null,
            "role_attrs": {},
            "sign_assertion": true,
            "sign_response": true,
            "signing_algorithm": "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256",
            "slo_url": "",
            "spinitiated_url": null,
            "static_attrs": null
          }
      },
      "trusted_device_days": 0,
      "type": "websdk",
      "username_normalization_policy": "None",
      "web_referers_enabled": 0
  }
}

Modify Integration (Legacy v2)

Change the name, greeting, and/or notes of the integration with integration key integration_key, or reset its secret key. When modifying an Admin API integration permissions can also be added or removed. Requires "Grant applications" API permission.

Note: This API call uses POST data, which must be represented as JSON and cannot be passed in via URL parameters. Some Duo clients (Python or Java, for example) offer helper functions to handle requests to the Admin API.

POST /admin/v2/integrations/[integration_key]

Parameters

Response Codes

Response Format

Returns the modified single integration object. Refer to Retrieve Integrations for an explanation of the object's keys.

Example Response

Same as Retrieve Integration by Integration Key.

Delete Integration (Legacy v2)

Delete the integration with integration_key from the system. Attempting to delete the Admin API integration whose secret key is used to sign this request will return an error. Requires "Grant applications" API permission.

DELETE /admin/v2/integrations/[integration_key]

Parameters

This API endpoint has no parameters.

Response Codes

Response Format

Empty string.

Example Response

{
  "stat": "OK",
  "response": ""
}

Retrieve Client Secret for an OAuth Integration (Legacy v2)

Retrieve the client_secret for the specified OAuth integration. Requires "Grant applications" API permission.

GET /admin/v2/integrations/oauth_cc/[integration_key]/client_secret/[client_id]

Parameters

This API endpoint has no parameters.

Response Codes

Response Format

Returns the client_secret.

Example Response

{
  "response": {
    "client_secret": "Zh5eGmUq9zpfQnyUIu5OL9iWoMMv5ZNmk3zLJ4Ep"
  },
  "stat": "OK"
}

Reset Client Secret for an OAuth Integration (Legacy v2)

Reset the client_secret for the specified OAuth integration. Requires "Grant applications" API permission.

POST /admin/v2/integrations/oauth_cc/[integration_key]/client_secret/[client_id]

Parameters

This API endpoint has no parameters.

Response Codes

Response Format

Empty string.

Example Response

{
  "response": {},
  "stat": "OK"
}

Retrieve Client Secret for an OIDC Integration (Legacy v2)

Retrieve the client_secret for the specified OIDC integration. Requires "Grant applications" API permission.

GET /admin/v2/integrations/oidc/[integration_key]/client_secret

Parameters

This API endpoint has no parameters.

Response Codes

Response Format

Returns the client_secret.

Example Response

{
  "response": {
    "client_secret": "Zh5eGmUq9zpfQnyUIu5OL9iWoMMv5ZNmk3zLJ4Ep"
  },
  "stat": "OK"
}

Reset Client Secret for an OIDC Integration (Legacy v2)

Reset the client_secret for the specified OIDC integration. Requires "Grant applications" API permission.

POST /admin/v2/integrations/oidc/[integration_key]/client_secret

Parameters

This API endpoint has no parameters.

Response Codes

Response Format

Empty string.

Example Response

{
  "response": {},
  "stat": "OK"
}

SSO Parameters (Legacy v2)

OAuth Parameters

OIDC Parameters

SAML Parameters

Policies

The Policies v2 API does not use the same authentication and request signing detailed earlier in this document. Our Python, Go, Java, and Node.JS API clients have been updated with the new authentication and signing requirements and include support for the Policies v2 API endpoints. We recommend you use the duo_client_python Python API client, the duo_api_golang Go API client, the duo_client_java Java API client, or the duo_api_nodejs Node.JS API client to interact with the Policies endpoints.

Summarize Policies

Returns policy names, keys, and applications or groups to which a policy is applied. Requires "Grant resource - Read" API permission.

GET /admin/v2/policies/summary

Parameters

This API endpoint has no parameters.

Response Codes

Response Format

Example Response

{
        "policies": [
            {
                "policy_applies_to": [
                    {
                        "app_integration_key": "DI29C05TCOFOX9QFZEKI",
                        "app_name": "Acme Corp Office 365",
                        "apply_type": "group_app",
                        "group_position": "0",
                        "groups": [
                            {
                                "group_id": "DGC00OELIG7CQD5AV958",
                                "group_name": "Contractors"
                            }
                        ]
                    }
                ],
                "policy_key": "PO0LORUX8W6GXFX27HR0",
                "policy_name": "12 hours Remembered Devices"
            },
            {
                "policy_applies_to": [
                    {
                        "app_integration_key": "DI29C05TCOFOX9QFZEKI",
                        "app_name": "Acme Corp Office 365",
                        "apply_type": "app"
                    }
                ],
                "policy_key": "PO0LBA709Z49E5XCHW06",
                "policy_name": "7 Days Remembered Devices"
            },
            {
                "policy_applies_to": [
                    {
                        "app_integration_key": "DI38Z0OPBEO4G8WE56OV",
                        "app_name": "Acme Cisco VPN",
                        "apply_type": "app"
                    },
                    {
                        "app_integration_key": "DION2T45OKE14FSYN4HN",
                        "app_name": "Windows Remote Desktop",
                        "apply_type": "app"
                    }
                ],
                "policy_key": "POAWMUK0XYZQ6BUPBEJF",
                "policy_name": "Deny All Unenrolled Users"
            },
            {
                "policy_applies_to": [],
                "policy_key": "PO9HIT6SE6TWQPVYZD6A",
                "policy_name": "Bypass MFA and Allow Unenrolled"
            },
            {
                "policy_applies_to": [
                    {
                        "app_integration_key": "DILSVDEYH66ZT8KIXGR9",
                        "app_name": "Acme Corp Office 365",
                        "apply_type": "group_app",
                        "group_position": "1",
                        "groups": [
                            {
                                "group_id": "DGIKLVP7LVU968UCDPVJ",
                                "group_name": "Verified Push Users"
                            }
                        ]
                    }
                ],
                "policy_key": "POWD3Z4WJIE3CF48A33K",
                "policy_name": "Verified Push"
            }
        ],
        "policy_count": 5,
        "response_is_truncated": false,
        "warnings": [
            "Policy 'Bypass MFA and Allow Unenrolled' is not applied to any groups or applications"
        ]
    },
    "stat": "OK"
}

Retrieve Policies

Retrieve a complete set of all policies. Includes all policy section data for each policy. Requires "Grant resource - Read" API permission.

GET /admin/v2/policies

Parameters

Use the paging parameters to change the number of results shown in a response or to retrieve additional results. See Response Paging for details.

This API endpoint has no additional parameters.

Response Codes