Duo Admin API

Overview

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.

In addition, 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

This API is automatically available to paying Duo Beyond, Duo Access, and Duo MFA plan customers. New customers with an Access or Beyond trial may Contact Duo Support to request Admin API access.

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).

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 will update our API documentation with new values in a timely fashion.

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 handlers for endpoints. In these cases, the API v1 handler remains supported, but will be limited or deprecated in the future. We encourage use of the v2 endpoints where available and recommend migrating existing API implementations to the v2 handlers.

Please note that all Unix timestamps are in seconds.

First Steps

Role required: Owner

Note that only administrators with the Owner role can create or modify an Admin API application in the Duo Admin Panel.

1. Sign up for a Duo account.
2. Log in to the Duo Admin Panel and navigate to Applications.
3. Click Protect an Application and locate the entry for Admin API in the applications list. Click Protect to the far-right to configure 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 in 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 what 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	The Admin API application can read information about, create, update, and delete 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 read information about, create, update, and delete Duo applications (referred to as "integrations" in the API).
   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 read resource	The Admin API application can read information about resource objects such as end users and devices.
   Grant write resource	The Admin API application can create, update, and delete resource objects such as end users and devices.

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 occurs 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.

Duo Security has demonstration clients available on Github to call the Duo API methods. Examples are available in: Python, Java, C#, Ruby, Perl, and PHP.

API Details

Base URL

All API methods use your API hostname, https://api-XXXXXXXX.duosecurity.com.

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.

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	Meaning
200	The request completed successfully.
401	The “Authorization”, “Date”, and/or “Content-Type” headers were missing or invalid.
403	This integration is not authorized for this endpoint or the ikey was created for a different integration type (for example, using an Auth API ikey with Admin API endpoints).
405	The request’s HTTP verb is not valid for this endpoint (for example, POST when only GET is supported).
429	The account has made too many requests of this type recently. Try again later.

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.

Metadata Information	Description
total_objects	The total number of objects retrieved by the API request across all pages of results.
next_offset	The offset from 0 at which to start the next paged set of results. If not present in the metadata response, then there are no more pages of results left.
prev_offset	The offset from 0 at which the previous paged set of results started. If you did not specify next_offset in the request, this defaults to 0 (the beginning of the results).

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

Paging Parameter	Required?	Description
limit	Optional	The maximum number of records returned in a paged set of results. Each endpoint that supports paged results has its own limit settings, specified like "Default: 100; Max: 300". If a request specifies a value greater than the endpoint's maximum limit, max value is used.
offset	Optional	The offset from 0 at which to start record retrieval. When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: 0

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:

Component	Description	Example
date	The current time, formatted as RFC 2822. This must be the same string as the “Date” header.	Tue, 21 Aug 2012 17:29:18 -0000
method	The HTTP method (uppercase)	POST
host	Your API hostname (lowercase)	api-xxxxxxxx.duosecurity.com
path	The specific API method’s path	/admin/v1/users
params	The URL-encoded list of key=value pairs, lexicographically sorted by key. These come from the request parameters (the URL query string for GET and DELETE requests or the request body for POST requests). If the request does not have any parameters one must still include a blank line in the string that is signed. Do not encode unreserved characters. Use upper-case hexadecimal digits A through F in escape sequences.	realname=First%20Last&username=root

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 RElXSjhYNkFFWU9SNU9NQzZUUTE6MmQ5N2Q2MTY2MzE5NzgxYjVhM2EwN2FmMzlkMzY2ZjQ5MTIzNGVkYw==
Host: api-XXXXXXXX.duosecurity.com
Content-Length: 35
Content-Type: application/x-www-form-urlencoded

Separate HTTP request header lines CRLF newlines.

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

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)}

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 read resource" API permission.

GET /admin/v1/users

Parameters

Paging Parameter	Required?	Description
limit	Optional	The maximum number of records returned. Default: 100; Max: 300
offset	Optional	The offset from 0 at which to start record retrieval. When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: 0

Query Parameter	Required?	Description
username	Optional	Specify a user name (or username alias) to look up a single user.

Response Codes

Response	Meaning
200	Success. Returns a list of users.
400	Invalid parameters.

Response Format

Key	Value
alias1...4	The user's username alias(es). Values included for backwards compatibility and reflect the same information as aliases.
aliases	Map of the user's username alias(es). Up to eight aliases may exist.
created	The user's creation date timestamp.
email	The user’s email address.
firstname	The user’s given name.
groups	List of groups to which this user belongs. See Retrieve Groups for response info.
is_enrolled	Is "true" if the user has a phone, hardware token, U2F token, or security key available for authentication. Otherwise, "false".
last_directory_sync	Timestamp of the last update to the user via directory sync, or “null” if the user has never synced with an external directory or if the directory that originally created the user has been deleted from Duo.
last_login	The last time this user logged in, as a UNIX timestamp, or “null” if the user has not logged in.
lastname	The user’s surname.
notes	Notes about this user. Viewable in the Duo Admin Panel.
phones	A list of phones that this user can use. See Retrieve Phones for descriptions of the phone response values.
realname	The user’s real name (or full name).
status	The user’s status. One of: Status Description “active” The user must complete secondary authentication. “bypass” The user will bypass secondary authentication after completing primary authentication. “disabled” The user will not be able to log in. “locked out” The user has been automatically locked out due to excessive authentication attempts. “pending deletion” The user was marked for deletion by a Duo admin from the Admin Panel, by the system for inactivity, or by directory sync. If not restored within seven days the user is permanently deleted. Note that when a user is a member of a group, the group status may override the individual user's status. Group status is not shown in the user response.
tokens	A list of tokens that this user can use. See Retrieve Hardware Tokens for descriptions of the response values.
u2f_tokens	A list of U2F tokens that this user can use. See Retrieve U2F Tokens for descriptions of the response values.
user_id	The user’s ID.
username	The user’s username.
webauthncredentials	A list of WebAuthn authenticators that this user can use. See Retrieve WebAuthn Credentials by User ID for descriptions of the response values.

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,
    "email": "jsmith@example.com",
    "firstname": "Joe",
    "groups": [{
      "desc": "People with hardware tokens",
      "group_id": "DGXXXXXXXXXXXXXXXXX",
      "mobile_otp_enabled": true,
      "name": "token_users",
      "push_enabled": true,
      "sms_enabled": true,
      "status": "Active",
      "voice_enabled": true  
    }],
    "is_enrolled": true,
    "last_directory_sync": 1508789163,
    "last_login": 1343921403,
    "lastname": "Smith",
    "notes": "",
    "phones": [{
      "activated": true,
      "capabilities": [
        "auto",
        "push",
        "sms",
        "phone",
        "mobile_otp"
      ],
      "encrypted": "Encrypted",
      "extension": "",
      "fingerprint": "Configured",
      "last_seen": "2019-11-18T15:51:13",
      "model": "Apple iPhone 11 Pro",
      "name": "My iPhone",
      "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": "0",
      "token_id": "DHIZ34ALBA2445ND4AI2",
      "type": "d1"
    }],
    "u2ftokens": [{
      "date_added": "1444678994",
      "registration_id": "D21RU6X1B1DF5P54B6PV"
    }],
    "user_id": "DU3RP9I2WOC59VZX672N",
    "username": "jsmith",
    "webauthncredentials": [
        {
            "credential_name": "Touch ID",
            "date_added": 1550685154,
            "label": "Touch ID",
            "webauthnkey": "WABFEOE007ZMV1QAZTRB"
        },
        {
            "credential_name": "YubiKey C",
            "date_added": 1550674764,
            "label": "Security Key",
            "webauthnkey": "WA4BD9AUVMSNUFWZGES4"
    }],
  }]
}

Create User

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

POST /admin/v1/users

Parameters

Parameter	Required?	Description
username	Required	The name of the user to create.
alias1...4	Optional	A username alias for the user. Up to four aliases may be specified with this parameter. Aliases must be unique amongst users. This parameter maintained for backwards compatibility. Mutually exclusive with aliases.
aliases	Optional	Username aliases for the user. Up to eight aliases may be specified with this parameter as a set of URL-encoded key-value pairs e.g. alias1=joe.smith&alias2=jsmith@example.com. Ignores alias position values not specified. Aliases must be unique amongst users. Mutually exclusive with alias1...4.
realname	Optional	The real name (or full name) of this user.
email	Optional	The email address of this user.
status	Optional	The user’s status. One of: Status Description “active” The user must complete secondary authentication. This is the default value if no status is specified. “bypass” The user will bypass secondary authentication after completing primary authentication. “disabled” The user will not be able to complete secondary authentication.
notes	Optional	An optional description or notes field. Can be viewed in the Admin Panel.
firstname	Optional	The user’s given name.
lastname	Optional	The user’s surname.

Response Codes

Response	Meaning
200	Success. Returns the newly created user.
400	Invalid or missing parameters, or user already exists with the given username.

Response Format

Returns the single object created. 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,
    "email": "jsmith@example.com",
    "firstname": "Joe",
    "groups": [],
    "is_enrolled": false,
    "last_directory_sync": null,
    "last_login": null,
    "lastname": "Smith",
    "notes": "",
    "phones": [],
    "realname": "Joe Smith",
    "status": "active",
    "tokens": [],
    "u2ftokens": [],
    "user_id": "DU3RP9I2WOC59VZX672N",
    "username": "jsmith",
  }]
}

Retrieve User by ID

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

GET /admin/v1/users/[user_id]

Parameters

None.

Response Codes

Response	Meaning
200	Success.
404	No user was found with the given user_id.

Response Format

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

Example Response

Same as Retrieve User.

Modify User

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

POST /admin/v1/users/[user_id]

Parameters

Parameter	Required?	Description
username	Optional	The new username.
alias1...4	Optional	A username alias for the user. Up to four aliases may be specified with this parameter. Aliases must be unique amongst users. This parameter maintained for backwards compatibility. Mutually exclusive with aliases.
aliases	Optional	Username aliases for the user. Up to eight aliases may be specified with this parameter as a set of URL-encoded key-value pairs e.g. alias1=joe.smith&alias2=jsmith@example.com. Ignores alias position values not specified. Remove the value for an existing alias by specifying a blank value e.g. alias1=. Aliases must be unique amongst users. Mutually exclusive with alias1...4.
realname	Optional	The new real name (or full name).
email	Optional	The new email address.
status	Optional	The new status. Must be one of “active”, “disabled”, or “bypass”. See Retrieve Users for an explanation of these fields.
notes	Optional	The new notes field.
firstname	Optional	The user’s new given name.
lastname	Optional	The user’s new surname.

Response Codes

Response	Meaning
200	The user was modified successfully. The user object is also returned (see Retrieve Users).
400	Invalid or missing parameters.
404	No user was found with the given user_id, or user already exists with the given username.

Response Format

Same as Retrieve Users.

Example Response

Same as Retrieve User by ID.

Delete User

Delete the user with ID user_id from the system. The API will not automatically delete phones associated with the user; remove them permanently with Delete Phone. This method returns 200 if the phone was found or if no such phone exists. Requires "Grant write resource" 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, inactive user expiration, or interactively from the Admin Panel, and therefore are not available for restoration. Users deleted via the API are immediately and permanently removed from Duo.

DELETE /admin/v1/users/[user_id]

Parameters

None.

Response Codes

Response	Meaning
200	The user was deleted or did not exist.

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 write resource" API permission.

POST /admin/v1/users/enroll

Parameters

Parameter	Required?	Description
username	Required	The user name (or username alias) of the user to enroll.
email	Required	The email address of this user.
valid_secs	Optional	The number of seconds the enrollment code should be valid for. Default: 2592000 (30 days).

Response Codes

Response	Meaning
200	The enrollment code was generated and the user was sent an enrollment email. The newly created enrollment code is also returned.
400	Invalid or missing parameter(s), or the user with the given username and email address already exists and is enrolled.

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. Requires "Grant write resource" API permission.

Object limits: 100 bypass codes per user.

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

Parameters

Parameter	Required?	Description
count	Optional	Number of new bypass codes to create. At most 10 codes (the default) can be created at a time. Codes will be generated randomly.
codes	Optional	CSV string of codes to use. Mutually exclusive with count.
reuse_count	Optional	The number of times generated bypass codes can be used. If 0, the codes will have an infinite reuse_count. Default: 1.
valid_secs	Optional	The number of seconds generated bypass codes should be valid for. If 0 (the default) the codes will never expire.

Response Codes

Response	Meaning
200	Success.
400	Invalid or missing parameters, or one-to-many object limit reached.
404	No user was found with the given user_id.
500	Other internal error.

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 read resource" API permission.

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

Parameters

Paging Parameter	Required?	Description
limit	Optional	The maximum number of records returned. Default: 100; Max: 500
offset	Optional	The offset from 0 at which to start record retrieval. When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: 0

Query Parameters

None.

Response Codes

Response	Meaning
200	Success.
404	No user was found with the given user_id.

Response Format

Key	Value
admin_email	The email address of the Duo administrator who created the bypass code.
bypass_code_id	The bypass code's identifier. Use with GET bypass code by ID.
created	The bypass code creation date timestamp.
expiration	The expiration timestamp of the bypass code, or "null" if the bypass code does not expire on a certain date.
reuse_count	The number of times the bypass code may be used before expiring, or "null" if the bypass code has no limit on the number of times it may be used.

Example Response

{
  "stat": "OK",
  "response": [{
    "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 read resource" API permission.

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

Parameters

Paging Parameter	Required?	Description
limit	Optional	The maximum number of records returned. Default: 100; Max: 500
offset	Optional	The offset from 0 at which to start record retrieval. When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: 0

Query Parameters

None.

Response Codes

Response	Meaning
200	Success.
404	No user was found with the given user_id.

Response Format

Same as for Retrieve Groups.

Example Response

{
  "response": [{
    "desc": "This is group A",
    "group_id": "DGXXXXXXXXXXXXXXXXXX",
    "mobile_otp_enabled": true,    
    "name": "Group A",
    "push_enabled": true,
    "sms_enabled": true,
    "status": "active",
    "voice_enabled": true
  },
  {
    "desc": "This is group B",
    "group_id": "DGXXXXXXXXXXXXXXXXXX",
    "mobile_otp_enabled": true,
    "name": "Group B (from Azure sync \"Acme Corp Azure AD\")"",
    "push_enabled": true,
    "sms_enabled": true,
    "status": "active",
    "voice_enabled": true
  }],
  "stat": "OK"
}

Associate Group with User

Associate a group with the user with ID user_id. Requires "Grant write resource" API permission.

Object limits: 100 groups per user.

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

Parameters

Parameter	Required?	Description
group_id	Required	The ID of the group to associate with the user.

Response Codes

Response	Meaning
200	Success. Returns a response of “”.
400	Invalid or missing parameters, one-to-many object limit reached, or nonexistent group_id. Also returns "Operation Failed" if the group does not exist.
404	Nonexistent user_id.
500	Other internal error.

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 write resource" API permission.

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

Parameters

None.

Response Codes

Response	Meaning
200	Success, or no such group exists.
404	No user was found with the given user_id.

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 read resource" API permission.

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

Parameters

Paging Parameter	Required?	Description
limit	Optional	The maximum number of records returned. Default: 100; Max: 500
offset	Optional	The offset from 0 at which to start record retrieval. When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: 0

Query Parameters

None.

Response Codes

Response	Meaning
200	Success.
404	No user was found with the given user_id.

Response Format

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

Example Response

{
  "stat": "OK",
  "response": [{
    "activated": false,
    "capabilities": [
      "sms",
      "phone",
      "push"
    ],
    "encrypted": "Encrypted",
    "extension": "",
    "fingerprint": "Configured",
    "last_seen": "2019-03-04T15:04:04",
    "model": "Google Pixel 2 Xl",
    "name": "",
    "number": "+15035550102",
    "phone_id": "DPFZRS9FB0D46QFTM890",
    "platform": "Google Android",
    "postdelay": "",
    "predelay": "",
    "screenlock": "Locked",
    "sms_passcodes_sent": true,
    "tampered": "Not tampered",
    "type": "Mobile"
  },
  {
    "activated": false,
    "capabilities": [
      "phone"
    ].
    "encrypted": "",
    "extension": "",
    "fingerprint": "",
    "last_seen": "",
    "model": "Unknown",
    "name": "",
    "number": "+15035550103",
    "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 write resource" API permission.

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

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

Parameters

Parameter	Required?	Description
phone_id	Required	The ID of the phone to associate with the user.

Response Codes

Response	Meaning
200	Success. Returns a response of “”.
400	Invalid or missing parameters, one-to-many object limit reached, or nonexistent phone_id.
404	Nonexistent user_id.
500	Other internal error.

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 write resource" API permission.

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

Parameters

None.

Response Codes

Response	Meaning
200	Success, or no such phone exists.
404	No user was found with the given user_id.

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 read resource" API permission.

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

Parameters

Paging Parameter	Required?	Description
limit	Optional	The maximum number of records returned. Default: 100; Max: 500
offset	Optional	The offset from 0 at which to start record retrieval. When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: 0

Query Parameters

None.

Response Codes

Response	Meaning
200	Success.
404	No user was found with the given user_id.

Response Format

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

Example Response

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

Associate Hardware Token with User

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

Object limits: 100 tokens per user.

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

Parameters

Parameter	Required?	Description
token_id	Required	The ID of the hardware token to associate with the user.

Response Codes

Response	Meaning
200	Success. Returns a response of “”.
400	Invalid or missing parameters, one-to-many object limit reached, token_id already in use by a different user, or nonexistent token_id.
404	Nonexistent user_id.
500	Other internal error.

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 write resource" API permission.

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

Parameters

None.

Response Codes

Response	Meaning
200	Success.
404	No user was found with the given user_id

Response Format

Empty string.

Example Response

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

Retrieve U2F Tokens by User ID

Returns a paged list of U2F 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 read resource" API permission.

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

Parameters

Paging Parameter	Required?	Description
limit	Optional	The maximum number of records returned. Default: 100; Max: 500
offset	Optional	The offset from 0 at which to start record retrieval. When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: 0

Query Parameters

None.

Response Codes

Response	Meaning
200	Success.
404	No user was found with the given user_id.

Response Format

Same as for Retrieve U2F Tokens, except U2F tokens have no users attribute.

Example Response

{
  "response": [{
    "date_added": 1446738417,
    "registration_id": "D2GIWFX1X1XXD1D6IP2W5"
  }],
  "stat": "OK"
}

{

}

Retrieve WebAuthn Credentials by User ID

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

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

Parameters

None.

Query Parameters

None.

Response Codes

Response	Meaning
200	Success.
404	No user was found with the given user_id.

Response Format

Key	Value
credential_name	Free-form label for the WebAuthn credential.
date_added	The date the WebAuthn credential was registered in Duo.
label	Indicates the type of WebAuthn credential. One of: “Security Key” or “Touch ID”.
webauthnkey	The WebAuthn credential's registration identifier.

Example Response

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

Synchronize User from Directory

Initiate a sync for 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. Requires "Grant write resource" API permission.

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

Parameters

Parameter	Required?	Description
username	Required	The user to update via directory sync. This should be the same as the user's username in the source directory.

Response Codes

Response	Meaning
200	The user was synced successfully. The user object is also returned (see Retrieve Users).
404	The specified username or directory_key was incorrect, or the user is not managed by the specified directory.
429	Too many requests; try again later.

Response Format

Same as Retrieve Users.

Example Response

Same as Retrieve User by ID.

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 read resource" API permission.

GET /admin/v1/groups

Parameters

Paging Parameter	Required?	Description
limit	Optional	The maximum number of records returned. Default: 100; Max: 100
offset	Optional	The offset from 0 at which to start record retrieval. When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: 0

Query Parameters

None.

Response Codes

Response	Meaning
200	Success.

Response Format

Key	Value
desc	The group’s description.
group_id	The group’s ID.
mobile_otp_enabled	If true, users in the group will be able to authenticate with a passcode generated by Duo Mobile. If false, users in the group will not be able to authenticate with a passcode generated by Duo Mobile. Note that this setting has no effect if Duo Mobile passcodes are disabled globally.
name	The group’s name. If managed by directory sync, then the name returned here also indicates the source directory.
push_enabled	If true, users in the group will be able to use Duo Push to authenticate. If false, users in the group will not be able to use Duo Push to authenticate. Note that this setting has no effect if Duo Push is disabled globally.
sms_enabled	If true, users in the group will be able to use SMS passcodes to authenticate. If false, users in the group will not be able to use SMS passcodes to authenticate. Note that this setting has no effect if SMS passcodes are disabled globally.
status	The group’s authentication status. May be one of: Status Description “active” The users in the group must complete secondary authentication. “bypass” The users in the group will bypass secondary authentication after completing primary authentication. “disabled” The users in the group will not be able to authenticate.
voice_enabled	If true, users in the group will be able to authenticate with a voice callback. If false, users in the group will not be able to authenticate with a voice callback. Note that this setting has no effect if voice callback is disabled globally.

Example Response

{
  "response": [{
    "desc": "This is group A",
    "group_id": "DGXXXXXXXXXXXXXXXXXX",
    "mobile_otp_enabled": true,    
    "name": "Group A",
    "push_enabled": true,
    "sms_enabled": true,
    "status": "active",
    "voice_enabled": true
  },
  {
    "desc": "This is group B",
    "group_id": "DGXXXXXXXXXXXXXXXXXX",
    "mobile_otp_enabled": true,
    "name": "Group B (from Azure sync \"Acme Corp Azure AD\")"",
    "push_enabled": true,
    "sms_enabled": true,
    "status": "active",
    "voice_enabled": true
  }],
  "stat": "OK"
}

Create Group

Create a new group. Requires "Grant write resource" API permission.

POST /admin/v1/groups

Parameters

Parameter	Required?	Description
name	Required	The name of the group.
desc	Optional	The description of the group.
push_enabled	Optional	If true, users in the group will be able to use Duo Push to authenticate. If false, users in the group will not be able to use Duo Push to authenticate. Note that this setting has no effect if Duo Push is disabled globally.
sms_enabled	Optional	If true, users in the group will be able to use SMS passcodes to authenticate. If false, users in the group will not be able to use SMS passcodes to authenticate. Note that this setting has no effect if SMS passcodes are disabled globally.
voice_enabled	Optional	If true, users in the group will be able to authenticate with a voice callback. If false, users in the group will not be able to authenticate with a voice callback. Note that this setting has no effect if voice callback is disabled globally.
mobile_otp_enabled	Optional	If true, users in the group will be able to authenticate with a passcode generated by Duo Mobile. If false, users in the group will not be able to authenticate with a passcode generated by Duo Mobile. Note that this setting has no effect if Duo Mobile passcodes are disabled globally.
status	Optional	The authentication status of the group. See Retrieve Groups for a list of possible values.

Response Codes

Response	Meaning
200	Success.
400	Group with given name already exists or one of the parameters is invalid.

Response Format

Key	Value
desc	The group’s description.
push_enabled	If true, users in the group will be able to use Duo Push to authenticate. If false, users in the group will not be able to use Duo Push to authenticate. Note that this setting has no effect if Duo Push is disabled globally.
sms_enabled	If true, users in the group will be able to use SMS passcodes to authenticate. If false, users in the group will not be able to use SMS passcodes to authenticate. Note that this setting has no effect if SMS passcodes are disabled globally.
voice_enabled	If true, users in the group will be able to authenticate with a voice callback. If false, users in the group will not be able to authenticate with a voice callback. Note that this setting has no effect if voice callback is disabled globally.
mobile_otp_enabled	If true, users in the group will be able to authenticate with a passcode generated by Duo Mobile. If false, users in the group will not be able to authenticate with a passcode generated by Duo Mobile. Note that this setting has no effect if Duo Mobile passcodes are disabled globally.
group_id	The group’s ID.
name	The group’s name.
status	The group’s authentication status. See Retrieve Groups for a list of possible values.

Example Response

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

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 read resource" API permission.

GET /admin/v2/groups/[group_id]

Parameters

None.

Response Codes

Response	Meaning
200	Success.
404	Group with given ID was not found.

Response Format

Key	Value
desc	The group’s description.
push_enabled	If true, users in the group will be able to use Duo Push to authenticate. If false, users in the group will not be able to use Duo Push to authenticate. Note that this setting has no effect if Duo Push is disabled globally.
sms_enabled	If true, users in the group will be able to use SMS passcodes to authenticate. If false, users in the group will not be able to use SMS passcodes to authenticate. Note that this setting has no effect if SMS passcodes are disabled globally.
voice_enabled	If true, users in the group will be able to authenticate with a voice callback. If false, users in the group will not be able to authenticate with a voice callback. Note that this setting has no effect if voice callback is disabled globally.
mobile_otp_enabled	If true, users in the group will be able to authenticate with a passcode generated by Duo Mobile. If false, users in the group will not be able to authenticate with a passcode generated by Duo Mobile. Note that this setting has no effect if Duo Mobile passcodes are disabled globally.
group_id	The group’s ID.
name	The group’s name. If managed by directory sync, then the name returned here also indicates the source directory.
status	The group’s authentication status. See Retrieve Groups for a list of possible values.

Example Response

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

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

Paging Parameter	Required?	Description
limit	Optional	The maximum number of records returned. Default: 100; Max: 500
offset	Optional	The offset from 0 at which to start record retrieval. When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: 0

Response Codes

Response	Meaning
200	Success.
400	Invalid parameters.
404	Group with given ID was not found.

Response Format

Key	Value
user_id	The user’s ID.
username	The user’s username.

Example Response

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

Get Group Info (Legacy v1)

The v1 groups endpoint limits the response to the first 4,000 group members. Consider migrating to the v2 endpoint. Requires "Grant read resource" API permission.

GET /admin/v1/groups/[group_id]

Parameters

None.

Response Codes

Response	Meaning
200	Success.
404	Group with given ID was not found.

Response Format

Key	Value
desc	The group’s description.
push_enabled	If true, users in the group will be able to use Duo Push to authenticate. If false, users in the group will not be able to use Duo Push to authenticate. Note that this setting has no effect if Duo Push is disabled globally.
sms_enabled	If true, users in the group will be able to use SMS passcodes to authenticate. If false, users in the group will not be able to use SMS passcodes to authenticate. Note that this setting has no effect if SMS passcodes are disabled globally.
voice_enabled	If true, users in the group will be able to authenticate with a voice callback. If false, users in the group will not be able to authenticate with a voice callback. Note that this setting has no effect if voice callback is disabled globally.
mobile_otp_enabled	If true, users in the group will be able to authenticate with a passcode generated by Duo Mobile. If false, users in the group will not be able to authenticate with a passcode generated by Duo Mobile. Note that this setting has no effect if Duo Mobile passcodes are disabled globally.
group_id	The group’s ID.
name	The group’s name. If managed by directory sync, then the name returned here also indicates the source directory.
status	The group’s authentication status. See Retrieve Groups for a list of possible values.
users	A list of the users in the group.

Example Response

{
  "response": {
    "desc": "Group description",
    "group_id": "DGXXXXXXXXXXXXXXXXXX",
    "mobile_otp_enabled": true,
    "name": "Group Name",
    "push_enabled": true,
    "sms_enabled": true,
    "status": "active",
    "users": [{
      "user_id": "DUXXXXXXXXXXXXXXXXXX",
      "username": "User A"
    },
    {
      "user_id": "DUXXXXXXXXXXXXXXXXXX",
      "username": "User B"
    }],
    "voice_enabled": true
  },
  "stat": "OK"
}

Update Group

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

POST /admin/v1/groups/[group_id]

Parameters

Parameter	Required?	Description
name	Optional	Update the name of the group.
desc	Optional	Update the description of the group.
push_enabled	Optional	If true, users in the group will be able to use Duo Push to authenticate. If false, users in the group will not be able to use Duo Push to authenticate. Note that this setting has no effect if Duo Push is disabled globally.
sms_enabled	Optional	If true, users in the group will be able to use SMS passcodes to authenticate. If false, users in the group will not be able to use SMS passcodes to authenticate. Note that this setting has no effect if SMS passcodes are disabled globally.
voice_enabled	Optional	If true, users in the group will be able to use authenticate with a voice callback. If false, users in the group will not be able to authenticate with a voice callback. Note that this setting has no effect if voice callback is disabled globally.
mobile_otp_enabled	Optional	If true, users in the group will be able to authenticate with a passcode generated by Duo Mobile. If false, users in the group will not be able to authenticate with a passcode generated by Duo Mobile. Note that this setting has no effect if Duo Mobile passcodes are disabled globally.
status	Optional	The authentication status of the group. See Retrieve Groups for a list of possible values.

Response Codes

Response	Meaning
200	Success.
400	Invalid parameters.
404	Group with given ID was not found.

Response Format

Key	Value
desc	The group’s updated description.
push_enabled	If true, users in the group will be able to use Duo Push to authenticate. If false, users in the group will not be able to use Duo Push to authenticate. Note that this setting has no effect if Duo Push is disabled globally.
sms_enabled	If true, users in the group will be able to use SMS passcodes to authenticate. If false, users in the group will not be able to use SMS passcodes to authenticate. Note that this setting has no effect if SMS passcodes are disabled globally.
voice_enabled	If true, users in the group will be able to authenticate with a voice callback. If false, users in the group will not be able to authenticate with a voice callback. Note that this setting has no effect if voice callback is disabled globally.
mobile_otp_enabled	If true, users in the group will be able to authenticate with a passcode generated by Duo Mobile. If false, users in the group will not be able to authenticate with a passcode generated by Duo Mobile. Note that this setting has no effect if Duo Mobile passcodes are disabled globally.
group_id	The group’s ID.
name	The group’s updated name.
status	The group’s updated authentication status. See Retrieve Groups for a list of possible values.

Example Response

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

Delete Group

Delete a group. Requires "Grant write resource" API permission.

DELETE /admin/v1/groups/[group_id]

Parameters

None.

Response Codes

Response	Meaning
200	The group was deleted or did not exist.

Response Format

None.

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 read resource" API permission.

GET /admin/v1/phones

Parameters

Paging Parameter	Required?	Description
limit	Optional	The maximum number of records returned. Default: 100; Max: 500
offset	Optional	The offset from 0 at which to start record retrieval. When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: 0

Query Parameters

Parameter	Required?	Description
number	Optional	Specify a phone number to look up a single phone.
extension	Optional	The extension, if necessary.

Response Codes

Response	Meaning
200	Success.
400	Invalid number.

Response Format

Key	Value
activated	Has this phone been activated for Duo Mobile yet? Either “true” or “false”.
capabilities	List of strings, each a factor that can be used with the device. Capability Meaning push The device is activated for Duo Push. phone The device can receive phone calls. sms The device can receive batches of SMS passcodes. mobile_otp The device can generate passcodes with Duo Mobile.
encrypted	The encryption status of an Android or iOS device file system. One of: “Encrypted”, “Unencrypted”, or “Unknown”. Blank for other platforms. This information is available to Duo Beyond and Duo Access plan customers.
extension	An extension, if necessary.
fingerprint	Whether an Android or iOS phone is configured for biometric verification. One of: “Configured”, “Disabled”, or “Unknown”. Blank for other platforms. This information is available to Duo Beyond and Duo Access plan customers.
last_seen	The timestamp of the last contact between Duo's service and the activated Duo Mobile app installed on the phone. Blank if the device has never activated Duo Mobile or if the platform does not support it.
model	The phone's model.
name	Free-form label for the phone.
number	The phone number. A phone with a smartphone platform but no number is a tablet.
phone_id	The phone’s ID.
platform	The phone platform. One of: “unknown”, “google android”, “apple ios”, “windows phone 7”, “rim blackberry”, “java j2me”, “palm webos”, “symbian os”, “windows mobile”, or “generic smartphone”. “windows phone” is accepted as a synonym for “windows phone 7”. This includes devices running Windows Phone 8. If a smartphone’s exact platform is unknown but it will have Duo Mobile installed, use “generic smartphone” and generate an activation code. When the phone is activated its platform will be automatically detected.
postdelay	The time (in seconds) to wait after the extension is dialed and before the speaking the prompt.
predelay	The time (in seconds) to wait after the number picks up and before dialing the extension.
screenlock	Whether screen lock is enabled on an Android or iOS phone. One of: “Locked”, “Unlocked”, or “Unknown”. Blank for other platforms. This information is available to Duo Beyond and Duo Access plan customers.
sms_passcodes_sent	Have SMS passcodes been sent to this phone? Either “true” or “false”.
tampered	Whether an iOS or Android device is jailbroken or rooted. One of: “Not Tampered”, “Tampered”, or “Unknown”. Blank for other platforms. This information is available to Duo Beyond and Duo Access plan customers.
type	The type of phone. One of: “unknown”, “mobile”, or “landline”.
users	A list of users associated with this phone.

Example Response

{
  "stat": "OK",
  "response": [{
    "activated": true,
    "capabilities": [
      "push",
      "sms",
      "phone",
      "mobile_otp"
    ],
    "encrypted": "Encrypted",
    "extension": "",
    "fingerprint": "Configured",
    "last_seen": "2019-03-04T15:04:04",
    "model": "Google Pixel 2 Xl",
    "name": "",
    "number": "+15555550100",
    "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",
      "firstname": "Joe",
      "is_enrolled": false,
      "last_directory_sync": null,
      "last_login": 1474399627,
      "lastname": "Smith",
      "notes": "",
      "realname": "Joe Smith",
      "status": "active",
      "user_id": "DUJZ2U4L80HT45MQ4EOQ",
      "username": "jsmith",
    }]
  }]
}

Create Phone

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

POST /admin/v1/phones

Parameters

Parameter	Required?	Description
number	Optional	The phone number. A phone with a smartphone platform but no number is a tablet.
name	Optional	Free-form label for the phone.
extension	Optional	The extension.
type	Optional	The phone type. See Retrieve Phones for a list of possible values.
platform	Optional	The phone platform. See Retrieve Phones for a list of possible values.
predelay	Optional	The time (in seconds) to wait after the number picks up and before dialing the extension.
postdelay	Optional	The time (in seconds) to wait after the extension is dialed and before the speaking the prompt.

Response Codes

Response	Meaning
200	The phone was created successfully. The newly created phone is also returned (see Retrieve Phones).
400	Invalid or missing parameter(s), or phone already exists with the given number and extension.

Response Format

Same as Retrieve Phone by ID.

Example Response

Same as Retrieve Phone by ID.

Retrieve Phone by ID

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

GET /admin/v1/phones/[phone_id]

Parameters

None.

Response Codes

Response	Meaning
200	Success.
404	No phone was found with the given phone_id.

Response Format

Same as Retrieve Phones.

Example Response

{
  "stat": "OK",
  "response": [{
    "activated": true,
    "capabilities": [
      "push",
      "sms",
      "phone",
      "mobile_otp"
    ],
    "encrypted": "Encrypted",
    "extension": "",
    "fingerprint": "Configured",
    "last_seen": "2019-03-04T15:04:04",
    "model": "Google Pixel 2 Xl",
    "name": "",
    "number": "+15555550100",
    "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",
      "firstname": "Joe",
      "is_enrolled": false,
      "last_directory_sync": null,
      "last_login": 1474399627,
      "lastname": "Smith",
      "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 write resource" API permission.

POST /admin/v1/phones/[phone_id]

Parameters

Parameter	Required?	Description
number	Optional	The new number.
name	Optional	Free-form label for the phone.
extension	Optional	The new extension.
type	Optional	The phone type. See Retrieve Phones for a list of possible values.
platform	Optional	The phone platform. See Retrieve Phones for a list of possible values.
predelay	Optional	The time (in seconds) to wait after the number picks up and before dialing the extension.
postdelay	Optional	The time (in seconds) to wait after the extension is dialed and before the speaking the prompt.

Response Codes

Response	Meaning
200	The phone was modified successfully. The phone object is returned.
400	Invalid or missing parameter(s), or phone already exists with the given number and extension.
404	No phone was found with the given phone_id.

Response Format

Same as Retrieve Phone by ID.

Example Response

Same as Retrieve Phone by ID.

Delete Phone

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

DELETE /admin/v1/phones/[phone_id]

Parameters

None.

Response Codes

Response	Meaning
200	The phone was deleted or did not exist.

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 write resource" API permission.

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

Parameters

Parameter	Required?	Description
valid_secs	Optional	The number of seconds this activation code should be valid for. Default: 86400 (one day).
install	Optional	“1” to also return an installation URL for Duo Mobile; “0” to not return. Default: “0”.

Response Codes

Response	Meaning
200	The activation code was successfully generated.
400	Invalid parameters or invalid phone. The phone’s platform must be one on which Duo Mobile can be activated.
404	No phone was found with the given phone_id.

Response Format

Key	Value
activation_url	Opening this URL with the Duo Mobile app will complete activation.
activation_barcode	URL of a QR code. Scan the code with Duo Mobile to complete activation. This QR code uses the same activation code as activation_url.
installation_url	Opening this URL on the phone will prompt the user to install Duo Mobile. Only present if install was “1”.
valid_secs	The number of seconds that the activation code is valid for.

Example Response

{
  "stat": "OK",
  "response": {
    "activation_barcode": "https://api-abcdef.duosecurity.com/frame/qr?value=duo%3A%2F%2Factivation-code",
    "activation_url": "https://m-abcdef.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 write resource" API permission.

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

Parameters

Parameter	Required?	Description
valid_secs	Optional	The number of seconds this activation code should be valid for. Default: 86400 (one day).
install	Optional	“1” to cause an installation SMS message to be sent before the activation message, “0” to not send an installation SMS message. Default: “0”.
installation_msg	Optional	A custom installation message to send to the user. Only valid if installation was requested. Must contain the phrase “<insturl>”, which is replaced with the installation URL.
activation_msg	Optional	A custom activation message to send to the user. Must contain “<acturl>”, which is replaced with the activation URL.

Response Codes

Response	Meaning
200	The activation code was generated and sent successfully.
400	Invalid parameters or invalid phone. The phone must be able to receive SMS messages and its platform must be one on which Duo Mobile can be activated.
404	No phone was found with the given phone_id.
500	Failed to send SMS message or SMS message too long.

Response Format

Key	Value
activation_msg	The text of the activation message.
activation_barcode	URL of a QR code. Scan the code with Duo Mobile to complete activation. This QR code contains the same activation code as activation_url.
installation_msg	The text of the installation message. Only present if the install parameter was set to 1 in the request.
valid_secs	The number of seconds that the activation URL is valid for.

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 write resource" API permission.

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

Parameters

Parameter	Required?	Description
installation_msg	Optional	A custom installation message to send to the user. Must contain the phrase “<insturl>”, which is replaced with the installation URL.

Response Codes

Response	Meaning
200	The installation URL was successfully sent.
400	Invalid parameters or invalid phone. The phone must be able to receive SMS messages and its platform must be one on which Duo Mobile can be activated.
404	No phone was found with the given phone_id.
500	Failed to send SMS message or SMS message too long.

Response Format

Key	Value
installation_msg	The text of the installation message.

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 write resource" API permission.

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

Parameters

None.

Response Codes

Response	Meaning
200	The passcodes were generated and sent successfully.
404	No phone was found with the given phone_id.

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 read resource" API permission.

GET /admin/v1/tokens

Parameters

Paging Parameter	Required?	Description
limit	Optional	The maximum number of records returned. Default: 100; Max: 500
offset	Optional	The offset from 0 at which to start record retrieval. When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: 0

Query Parameters

Parameter	Required?	Description
type	Optional*	Specify a type and serial number to look up a single hardware token. One of: Type Description “h6” HOTP-6 hardware token “h8” HOTP-8 hardware token “yk” YubiKey AES hardware token “d1” Duo-D100 hardware token * This option is required if serial is present.
serial	Optional*	The serial number of the hardware token. * This option is required if type is present.

Response Codes

Response	Meaning
200	Success. Returns a list of tokens.
400	Invalid parameters.

Response Format

Key	Value
token_id	The hardware token’s unique ID.
type	The type of hardware token.
serial	The serial number of the hardware token, used to uniquely identify the hardware token when paired with type.
totp_step	Null for all supported token types.
users	A list of users that this hardware token is associated with.

Example Response

{
  "stat": "OK",
  "response": [{
    "serial": "0",
    "token_id": "DHIZ34ALBA2445ND4AI2",
    "type": "d1",
    "totp_step": null,
    "users": [{
      "user_id": "DUJZ2U4L80HT45MQ4EOQ",
      "username": "jsmith",
      "alias1": "joe.smith",
      "alias2": "jsmith@example.com",
      "alias3": null,
      "alias4": null,
      "aliases": {
          "alias1": "joe.smith",
          "alias2": "jsmith@example.com"
      },
      "realname": "Joe Smith",
      "email": "jsmith@example.com",
      "status": "active",
      "last_login": 1343921403,
      "notes": ""
    }]
  }]
}

Create Hardware Token

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

POST /admin/v1/tokens

Parameters

Parameter	Required?	Description
type	Required	The type of hardware token to import. One of: Type Description “h6” HOTP-6 hardware token “h8” HOTP-8 hardware token “yk” YubiKey AES hardware token Duo-D100 tokens (type "d1") are imported when purchased from Duo and may not be created via the Admin API.
serial	Required	The serial number of the token (maximum length 128 characters).
secret	Optional	The HOTP secret. This parameter is required for HOTP-6 and HOTP-8 hardware tokens.
counter	Optional	Initial value for the HOTP counter. Default: 0. This parameter is only valid for HOTP-6 and HOTP-8 hardware tokens.
private_id	Optional	The YubiKey private ID. This parameter is required for YubiKey hardware tokens.
aes_key	Optional	The YubiKey AES key. This parameter is required for YubiKey hardware tokens.

Response Codes

Response	Meaning
200	The hardware token was created successfully. The newly created hardware token is also returned (see Retrieve Hardware Tokens).
400	Invalid or missing parameter(s), or hardware token already exists with the given type and serial.

Response Format

Same as Retrieve Hardware Tokens.

Example Response

Same as Retrieve Hardware Token by ID.

Retrieve Hardware Token by ID

Return the single hardware token with token_id. Requires "Grant read resource" API permission.

GET /admin/v1/tokens/[token_id]

Parameters

None.

Response Codes

Response	Meaning
200	Success.
404	No hardware token was found with the given token_id.

Response Format

Same as Retrieve Hardware Tokens.

Example Response

{
  "stat": "OK",
  "response": {
    "serial": "0",
    "token_id": "DHIZ34ALBA2445ND4AI2",
    "type": "d1",
    "totp_step": null,
    "users": [{
      "user_id": "DUJZ2U4L80HT45MQ4EOQ",
      "username": "jsmith",
      "alias1": "joe.smith",
      "alias2": "jsmith@example.com",
      "alias3": null,
      "alias4": null,
      "aliases": {
          "alias1": "joe.smith",
          "alias2": "jsmith@example.com"
      },
      "realname": "Joe Smith",
      "email": "jsmith@example.com",
      "status": "active",
      "last_login": 1343921403,
      "notes": ""
    }]
  }
}

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 write resource" API permission.

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

Parameters

Parameter	Required?	Description
code1	Required	The first code from the token.
code2	Required	The first code from the token.
code3	Required	The first code from the token.

Response Codes

Response	Meaning
200	The token was resynced successfully.
400	Invalid or missing parameter(s) or cannot resynchronize tokens of this type.
404	No token was found with the given token_id.

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 write resource" API permission.

DELETE /admin/v1/tokens/[token_id]

Parameters

None.

Response Codes

Response	Meaning
200	The token was deleted or did not exist.

Response Format

Empty string.

Example Response

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

U2F Tokens

Per-user U2F Token Operations

See Retrieve U2F Tokens by User ID.

Retrieve U2F Tokens

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

GET /admin/v1/u2ftokens

Parameters

Paging Parameter	Required?	Description
limit	Optional	The maximum number of records returned. Default: 100; Max: 500
offset	Optional	The offset from 0 at which to start record retrieval. When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: 0

Response Codes

Response	Meaning
200	Success. Returns a list of U2F tokens.

Response Format

Key	Value
date_added	The date the U2F token was registered in Duo.
registration_id	The U2F token's registration identifier. Use with GET token by ID.
user	Selected information about the user attached to the U2F token. Type Description alias1...4 The user's username alias(es). Up to four aliases may exist. created The user's creation date timestamp. email The user’s email address. firstname The user’s given name. is_enrolled Is "true" if the user has a phone, hardware token, U2F token, or security key available for authentication. Otherwise, "false". last_directory_sync Timestamp of the last update to the user via directory sync, or “null” if the user has never synced with an external directory or if the directory that originally created the user has been deleted from Duo. last_login The last time this user logged in, as a UNIX timestamp, or “null” if the user has not logged in. lastname The user’s surname. notes Notes about this user. realname The user’s real name (or full name). status The user’s status. One of: Status Description “active” The user must complete secondary authentication. “bypass” The user will bypass secondary authentication after completing primary authentication. “disabled” The user will not be able to complete secondary authentication. “locked out” The user has been automatically locked out due to excessive authentication attempts. user_id The user’s ID. username The user’s username.

Example Response

{
  "stat": "OK",
  "response": [{
    "date_added": 1444678994,
    "registration_id": "D21RU6X1B1DF5P54B6PV",
    "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",
        "firstname": Joe,
        "is_enrolled": true,
        "last_directory_sync": 1384275337,
        "last_login": 1514922986,
        "lastname": Smith,
        "notes": "",
        "realname": "Joe Smith",
        "status": "active",
        "user_id": "DU3RP9I2WOC59VZX672N",
        "username": "jsmith",
    }]
  }]
}

Retrieve U2F Token by ID

Return the single U2F token with registration_id. Requires "Grant read resource" API permission.

GET /admin/v1/u2ftokens/[registration_id]

Parameters

None.

Response Codes

Response	Meaning
200	Success.
404	No U2F token was found with the given registration_id.

Response Format

Same as Retrieve U2F Tokens.

Example Response

{
  "stat": "OK",
  "response": [{
    "date_added": 1444678994,
    "registration_id": "D21RU6X1B1DF5P54B6PV",
    "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",
        "firstname": Joe,
        "is_enrolled": true,
        "last_directory_sync": 1384275337,
        "last_login": 1514922986,
        "lastname": Smith,
        "notes": "",
        "realname": "Joe Smith",
        "status": "active",
        "user_id": "DU3RP9I2WOC59VZX672N",
        "username": "jsmith",
    }]
  }]
}

Delete U2F Token

Delete the U2F token with ID registration_id from the system. Requires "Grant write resource" API permission.

DELETE /admin/v1/u2ftokens/[registration_id]

Parameters

None.

Response Codes

Response	Meaning
200	The U2F token with ID registration_id was deleted.
404	No U2F token was found with the given registration_id.

Response Format

Empty string.

Example Response

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

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 read resource" API permission.

GET /admin/v1/webauthncredentials

Parameters

Paging Parameter	Required?	Description
limit	Optional	The maximum number of records returned. Default: 100; Max: 500
offset	Optional	The offset from 0 at which to start record retrieval. When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: 0

Response Codes

Response	Meaning
200	Success. Returns a list of WebAuthn credentials.

Response Format

Key	Value
credential_name	Free-form label for the WebAuthn credential.
date_added	The date the WebAuthn credential was registered in Duo.
label	Indicates the type of WebAuthn credential. One of: “Security Key” or “Touch ID”.
user	Selected information about the user attached to the WebAuthn credential. Type Description alias1...4 The user's username alias(es). Up to four aliases may exist. created The user's creation date timestamp. email The user’s email address. firstname The user’s given name. is_enrolled Is "true" if the user has a phone, hardware token, WebAuthn credential, or security key available for authentication. Otherwise, "false". last_directory_sync Timestamp of the last update to the user via directory sync, or “null” if the user has never synced with an external directory or if the directory that originally created the user has been deleted from Duo. last_login The last time this user logged in, as a UNIX timestamp, or “null” if the user has not logged in. lastname The user’s surname. notes Notes about this user. realname The user’s real name (or full name). status The user’s status. One of: Status Description “active” The user must complete secondary authentication. “bypass” The user will bypass secondary authentication after completing primary authentication. “disabled” The user will not be able to complete secondary authentication. “locked out” The user has been automatically locked out due to excessive authentication attempts. user_id The user’s ID. username The user’s username.
webauthnkey	The WebAuthn credential's registration identifier.

Example Response

{
  "stat": "OK",
  "response": [{
    "credential_name": "YubiKey",
    "date_added": 1550674764,
    "label": "Security Key",
    "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",
        "firstname": Joe,
        "is_enrolled": true,
        "last_directory_sync": 1384275337,
        "last_login": 1514922986,
        "lastname": Smith,
        "notes": "",
        "realname": "Joe Smith",
        "status": "active",
        "user_id": "DU3RP9I2WOC59VZX672N",
        "username": "jsmith",
    }]
    "webauthnkey": "WA4ED9AUVMSWUF00KES4"
  }]
}

Retrieve WebAuthn Credentials by Key

Return the single WebAuthn credential with webauthnkey. Requires "Grant read resource" API permission.

GET /admin/v1/webauthncredentials/[webauthnkey]

Parameters

None.

Response Codes

Response	Meaning
200	Success.
404	No WebAuthn credential was found with the given webauthnkey.

Response Format

Same as Retrieve WebAuthn Credentials.

Example Response

{
  "stat": "OK",
  "response": [{
    "credential_name": "YubiKey",
    "date_added": 1550674764,
    "label": "Security Key",
    "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",
        "firstname": Joe,
        "is_enrolled": true,
        "last_directory_sync": 1384275337,
        "last_login": 1514922986,
        "lastname": Smith,
        "notes": "",
        "realname": "Joe Smith",
        "status": "active",
        "user_id": "DU3RP9I2WOC59VZX672N",
        "username": "jsmith",
    }]
    "webauthnkey": "WA4ED9AUVMSWUF00KES4"
  }]
}

Delete WebAuthn Credential

Delete the WebAuthn credential with key webauthnkey from the system. Requires "Grant write resource" API permission.

DELETE /admin/v1/webauthncredentials/[webauthnkey]

Parameters

None.

Response Codes

Response	Meaning
200	The WebAuthn credential with key webauthnkey was deleted.
404	No WebAuthn credential was found with the given webauthnkey.

Response Format

Empty string.

Example Response

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

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 read resource" API permission.

GET /admin/v1/bypass_codes

Parameters

Paging Parameter	Required?	Description
limit	Optional	The maximum number of records returned. Default: 100; Max: 500
offset	Optional	The offset from 0 at which to start record retrieval. When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: 0

Response Codes

Response	Meaning
200	Success. Returns metadata information for all bypass codes.

Response Format

Key	Value
admin_email	The email address of the Duo administrator who created the bypass code.
bypass_code_id	The bypass code's identifier.
created	The bypass code creation date timestamp.
expiration	The expiration timestamp of the bypass code, or "null" if the bypass code does not expire on a certain date.
reuse_count	The number of times the bypass code may be used before expiring, or "null" if the bypass code has no limit on the number of times it may be used.
user	Selected information about the user attached to the bypass code. Type Description alias1...4 The user's username alias(es). Up to four aliases may exist. created The user's creation date timestamp. email The user’s email address. firstname The user’s given name. is_enrolled Is "true" if the user has a phone, hardware token, U2F token, or security key available for authentication. Otherwise, "false". last_directory_sync Timestamp of the last update to the user via directory sync, or “null” if the user has never synced with an external directory or if the directory that originally created the user has been deleted from Duo. last_login The last time this user logged in, as a UNIX timestamp, or “null” if the user has not logged in. lastname The user’s surname. notes Notes about this user. realname The user’s real name (or full name). status The user’s status. One of: Status Description “active” The user must complete secondary authentication. “bypass” The user will bypass secondary authentication after completing primary authentication. “disabled” The user will not be able to complete secondary authentication. “locked out” The user has been automatically locked out due to excessive authentication attempts. user_id The user’s ID. username The user’s username.

Example Response

{
  "stat": "OK",
  "response": [{
    "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",
        "firstname": Joe,
        "is_enrolled": true,
        "last_directory_sync": 1384275337,
        "last_login": 1514922986,
        "lastname": Smith,
        "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 read resource" API permission.

GET /admin/v1/bypass_codes/[bypass_code_id]

Parameters

None.

Response Codes

Response	Meaning
200	Success.
404	No bypass code was found with the given bypass_code_id.

Response Format

Same as Retrieve Bypass Codes.

Example Response

{
  "stat": "OK",
  "response": [{
    "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",
        "firstname": Joe,
        "is_enrolled": true,
        "last_directory_sync": 1384275337,
        "last_login": 1514922986,
        "lastname": Smith,
        "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 write resource" API permission.

DELETE /admin/v1/bypass_codes/[bypass_code_id]

Parameters

None.

Response Codes

Response	Meaning
200	The bypass code was deleted.
404	No bypass code was found with the given bypass_code_id.

Response Format

Empty string.

Example Response

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

Integrations

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 applications" API permission.

GET /admin/v1/integrations

Parameters

Paging Parameter	Required?	Description
limit	Optional	The maximum number of records returned. Default: 100; Max: 500
offset	Optional	The offset from 0 at which to start record retrieval. When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: 0

Response Codes

Response	Meaning
200	Success.

Response Format

Key	Value
adminapi_admins	1 if the integration has been granted permission for Administrators methods; 0 otherwise. Only applicable to Admin API integrations.
adminapi_info	1 if the integration has been granted permission for Account Info methods; 0 otherwise. Only applicable to Admin API integrations.
adminapi_integrations	1 if the integration has been granted permission for Integrations methods; 0 otherwise. Only applicable to Admin API integrations.
adminapi_read_log	1 if the integration has been granted permission for Logs methods; 0 otherwise. Only applicable to Admin API integrations.
adminapi_read_resource	1 if the integration has been granted permission to retrieve objects like users, phones, and hardware tokens; 0 otherwise. Only applicable to Admin API integrations.
adminapi_settings	1 if the integration has been granted permission for Settings methods; 0 otherwise. Only applicable to Admin API integrations.
adminapi_write_resource	1 if the integration has been granted permission to modify objects like users, phones, and hardware tokens; 0 otherwise. Only applicable to Admin API integrations.
enroll_policy	What to do after an unenrolled user passes primary authentication. One of: Policy Description “enroll” The user will be prompted to enroll in Duo. “allow” The user will be signed in, skipping any secondary authentication. “deny” The user may not enroll in Duo or skip secondary authentication, and therefore cannot access the application.
frameless_auth_prompt_enabled	1 if the integration has been updated to support Duo Universal Prompt, otherwise 0. Only appears for a given integration after Duo makes the frameless prompt available.
greeting	Voice greeting read before the authentication instructions to users who authenticate with a phone callback.
groups_allowed	A list of groups, as group IDs, that are allowed to authenticate with the integration. If empty, all groups are allowed.
integration_key	Integration ID.
ip_whitelist	CSV string of IPs/Ranges from which the second authentication factor will not be required, will be returned as an array. Example: “192.0.2.8,198.51.100.0-198.51.100.20,203.0.113.0/24”. Supported with these integration types: Type Description “1password” 1Password “adfs” Microsoft ADFS “agadobe_documentcloud” SAML - Adobe Document Cloud “agasana” SAML - Asana “agaws” SAML - Amazon Web Services “agatlassian-cloud” SAML - Atlassian Cloud “agbamboohr” SAML - BambooHR “agbluejeans” SAML - BlueJeans “agbomgar” SAML - Bomgar “agbonusly” SAML - Bonusly “agbox” SAML - Box “agcanvas” SAML - Canvas “agclarizen” SAML - Clarizen “agcloudlock” SAML - CloudLock “agconfluence” SAML - Confluence “agcrashplan” SAML - CrashPlan “agdatadog” SAML - Datadog “agdesk” SAML - Desk “agdocusign” SAML - DocuSign “agdropbox” SAML - Dropbox “agegnyte” SAML - Egnyte “agevernote” SAML - Evernote “agexpensify” SAML - Expensify “agfacebook” SAML - Facebook at Work “agfreshdesk” SAML - Freshdesk “aggeneric” SAML - Service Provider “aggithub-enterprise” SAML - GitHub Enterprise “aggoogle” SAML - Google Apps “aggotomeeting” SAML - GoToMeeting “aggreenhouse” SAML - Greenhouse “aghackerone” SAML - HackerOne “agheroku” SAML - Heroku “agintacct” SAML - Intacct “agjira” SAML - JIRA “agjitbit” SAML - Jitbit “aglooker” SAML - Looker “agmarketo” SAML - Marketo “agmeraki” SAML - Meraki “agnamely” SAML - Namely “agnewrelic” SAML - New Relic “agoffice365” SAML - Office 365 “agopendns” SAML - OpenDNS “agpagerduty” SAML - PagerDuty “agremedyforce” SAML - Remedyforce “agringcentral” SAML - RingCentral “agrobin” SAML - Robin “agsalesforce” SAML - Salesforce “agsamanage” SAML - Samanage “agsharefile” SAML - ShareFile “agsignalsciences” SAML - Signal Sciences “agslack” SAML - Slack “agsmartsheet” SAML - Smartsheet “agstatuspageio” SAML - StatusPage.io “agsugarcrm” SAML - SugarCRM “agsumologic” SAML - Sumo Logic “agsyncplicity” SAML - Syncplicity “agudemy” SAML - Udemy “aguservoice” SAML - UserVoice “agwebex” SAML - Cisco WebEx “agzendesk” SAML - Zendesk “agzoom” SAML - Zoom “array” Array SSL VPN “authapi” Auth API “barracuda” Barracuda SSL VPN “bitium” Bitium “caradigm” Caradigm “cas” CAS (Central Authentication Service) “cisco” Cisco SSL VPN “citrixcag” Citrix Access Gateway “citrixns” Citrix Gateway (formerly Citrix NetScaler) “clearpass” Aruba ClearPass “confluence” Confluence “dag” Duo Access Gateway “device-management-portal” Device Management Portal “drawbridgenetworks” Drawbridge Networks “drupal” Drupal “f5bigip” F5 BIG-IP APM “f5firepass” F5 FirePass SSL VPN “fortinet” Fortinet FortiGate SSL VPN “greyheller” Appsian Security Platform “jira” JIRA “juniper” Juniper SSL VPN “juniperuac” Juniper UAC “keeper” Keeper Security “lastpass” LastPass “okta” Okta “onelogin” OneLogin “owa” Microsoft OWA “paloalto” Palo Alto SSL VPN “pingfederate” PingFederate “rdgateway” Microsoft RD Gateway “rdp” Microsoft RDP “rdweb” Microsoft RD Web “resilient” Resilient Systems “rest” Auth API “sailpoint” SailPoint “shibboleth” Shibboleth “sonicwallsra” SonicWALL SRA SSL VPN “splunk” Splunk “unix” UNIX Application “websdk” Web SDK “wordpress” WordPress
ip_whitelist_enroll_policy	Policy for handling new users from IPs on the permit list. One of: Policy Description “enforce” The new user will be subject to the enrollment policy (i.e. enroll_policy). “allow” The new user will be signed in, skipping any policy defined by the enrollment policy.
name	The integration’s name.
networks_for_api_access	A comma-separated list of IP addresses, IP ranges, or CIDRs specifying the networks allowed to access this API integration. Only returned for Accounts API and Admin API integrations.
notes	Description of the integration.
policy_key	The identifying policy key for the custom policy attached to the integration. Not shown if no policy attached to the integration.
secret_key	Secret used when configuring systems to use this integration.
self_service_allowed	1 if users may use self-service from this integration's 2FA prompt to update authentication devices, otherwise false (default). Supported on the following integrations that display the interactive Duo authentication prompt in a web browser: Type Description “1password” 1Password “adfs” Microsoft ADFS “agadobe_documentcloud” SAML - Adobe Document Cloud “agasana” SAML - Asana “agaws” SAML - Amazon Web Services “agatlassian-cloud” SAML - Atlassian Cloud “agbamboohr” SAML - BambooHR “agbluejeans” SAML - BlueJeans “agbomgar” SAML - Bomgar “agbonusly” SAML - Bonusly “agbox” SAML - Box “agcanvas” SAML - Canvas “agclarizen” SAML - Clarizen “agcloudlock” SAML - CloudLock “agconfluence” SAML - Confluence “agcrashplan” SAML - CrashPlan “agdatadog” SAML - Datadog “agdesk” SAML - Desk “agdocusign” SAML - DocuSign “agdropbox” SAML - Dropbox “agegnyte” SAML - Egnyte “agevernote” SAML - Evernote “agexpensify” SAML - Expensify “agfacebook” SAML - Facebook at Work “agfreshdesk” SAML - Freshdesk “aggeneric” SAML - Service Provider “aggithub-enterprise” SAML - GitHub Enterprise “aggoogle” SAML - Google Apps “aggotomeeting” SAML - GoTo Apps “aggreenhouse” SAML - Greenhouse “aghackerone” SAML - HackerOne “agheroku” SAML - Heroku “agintacct” SAML - Intacct “agjira” SAML - JIRA “agjitbit” SAML - Jitbit “aglooker” SAML - Looker “agmarketo” SAML - Marketo “agmeraki” SAML - Meraki “agnamely” SAML - Namely “agnewrelic” SAML - New Relic “agoffice365” SAML - Office 365 “agopendns” SAML - OpenDNS “agpagerduty” SAML - PagerDuty “agremedyforce” SAML - Remedyforce “agringcentral” SAML - RingCentral “agrobin” SAML - Robin “agsalesforce” SAML - Salesforce “agsamanage” SAML - Samanage “agsharefile” SAML - ShareFile “agsignalsciences” SAML - Signal Sciences “agslack” SAML - Slack “agsmartsheet” SAML - Smartsheet “agstatuspageio” SAML - StatusPage.io “agsugarcrm” SAML - SugarCRM “agsumologic” SAML - Sumo Logic “agsyncplicity” SAML - Syncplicity “agudemy” SAML - Udemy “aguservoice” SAML - UserVoice “agwebex” SAML - Cisco WebEx “agzendesk” SAML - Zendesk “agzoom” SAML - Zoom “array” Array SSL VPN “barracuda” Barracuda SSL VPN “bitium” Bitium “cas” CAS (Central Authentication Service) “cisco” Cisco SSL VPN “citrixcag” Citrix Access Gateway “citrixns” Citrix Gateway (formerly Citrix NetScaler) “clearpass” Aruba ClearPass “confluence” Confluence “dag” Duo Access Gateway “device-management-portal” Device Management Portal “drawbridgenetworks” Drawbridge Networks “drupal” Drupal “f5bigip” F5 BIG-IP APM “f5firepass” F5 FirePass SSL VPN “fortinet” Fortinet FortiGate SSL VPN “greyheller” Appsian Security Platform “jira” JIRA “juniper” Juniper SSL VPN “okta” Okta “onelogin” OneLogin “owa” Microsoft OWA “paloalto” Palo Alto SSL VPN “pingfederate” PingFederate “rdweb” Microsoft RD Web “resilient” Resilient Systems “shibboleth” Shibboleth “sonicwallsra” SonicWALL SRA SSL VPN “splunk” Splunk “websdk” Web SDK “wordpress” WordPress
type	Integration type. One of Type Description “1password” 1Password “accountsapi” Accounts API “adfs” Microsoft ADFS “adminapi” Admin API “aeries” Aeries SIS “agadobe_documentcloud” SAML - Adobe Document Cloud “agaha” SAML - Aha! “agasana” SAML - Asana “agaws” SAML - Amazon Web Services “agatlassian-cloud” SAML - Atlassian Cloud “agbamboohr” SAML - BambooHR “agbarracuda-waf” SAML - Barracuda WAF “agbluejeans” SAML - BlueJeans “agbomgar” SAML - Bomgar “agbonusly” SAML - Bonusly “agbox” SAML - Box “agbugsnag” SAML - Bugsnag “agcanvas” SAML - Canvas “agclarizen” SAML - Clarizen “agcloudlock” SAML - CloudLock “agconfluence” SAML - Confluence “agcrashplan” SAML - CrashPlan “agcyberark” SAML - CyberArk Privileged Account Security “agdatadog” SAML - Datadog “agdesk” SAML - Desk “agdigicert” SAML - DigiCert “agdng” SAML - Duo Network Gateway “agdocusign” SAML - DocuSign “agdropbox” SAML - Dropbox “agduo-adminpanel” SAML - Duo Admin Panel “agegnyte” SAML - Egnyte “agevernote” SAML - Evernote “agexpensify” SAML - Expensify “agfacebook” SAML - Workplace by Facebook “agfreshdesk” SAML - Freshdesk “aggeneric” SAML - Service Provider “aggithub-business” SAML - GitHub.com for Business “aggithub-enterprise” SAML - GitHub Enterprise “aggoogle” SAML - G Suite “aggotomeeting” SAML - GoToMeeting “aggreenhouse” SAML - Greenhouse “aghackerone” SAML - HackerOne “aghackerrank” SAML - HackerRank for Work “agheroku” SAML - Heroku “aghipchat” SAML - HipChat “agigloo” SAML - Igloo “agintacct” SAML - Intacct “agjamf-jss” SAML - Jamf Pro “agjira” SAML - JIRA “agjitbit” SAML - Jitbit “aglooker” SAML - Looker “agmarketo” SAML - Marketo “agmeraki” SAML - Meraki “agmonday” SAML - Monday “agnamely” SAML - Namely “agnetdocuments” SAML - NetDocuments “agnewrelic” SAML - New Relic “agoffice365” SAML - Office 365 “agopendns” SAML - OpenDNS “agpagerduty” SAML - PagerDuty “agpaloalto-aperture” SAML - Palo Alto Networks Aperture “agpaloalto” SAML - Palo Alto Networks “agremedyforce” SAML - Remedyforce “agringcentral” SAML - RingCentral “agrobin” SAML - Robin “agsalesforce” SAML - Salesforce “agsamanage” SAML - Samanage “agsaucelabs” SAML - Saucelabs “agsharefile” SAML - ShareFile “agsignalsciences” SAML - Signal Sciences “agslack” SAML - Slack “agsmartsheet” SAML - Smartsheet “agstatuspageio” SAML - StatusPage.io “agsugarcrm” SAML - SugarCRM “agsumologic” SAML - Sumo Logic “agsyncplicity” SAML - Syncplicity “agtableau-online” SAML - Tableau Online “agtableau” SAML - Tableau “agudemy” SAML - Udemy “aguservoice” SAML - UserVoice “agwebex” SAML - Cisco Webex Meetings (with Site Admin) “agwebex-controlhub” SAML - Cisco Webex (with Control Hub) “agworkday” SAML - Workday “agzendesk” SAML - Zendesk “agzoom” SAML - Zoom “akamai-eaa” Akamai Enterprise Application Access “array” Array SSL VPN “aws-directory-service” AWS Directory Service “azure-ca” Microsoft Azure Active Directory “authapi” Auth API “barracuda” Barracuda SSL VPN “bitium” Bitium “bitwarden” Bitwarden “bomgar” Bomgar “caradigm” Caradigm “cas” CAS (Central Authentication Service) “checkpoint” Check Point VPN “cisco” Cisco ASA SSL VPN “ciscofirepower” Cisco Firepower Threat Defense VPN “ciscoiseradius” Cisco ISE “ciscoradius” Cisco RADIUS VPN “citrixcag” Citrix Access Gateway “citrixns” Citrix Gateway (formerly Citrix NetScaler) “clearpass” Aruba ClearPass “confluence” Confluence “cyberark” CyberArk Privileged Account Security LDAP/RADIUS “cyberarkweb” CyberArk Privileged Account Security “dag” Duo Access Gateway Launcher “device-management-portal” Device Management Portal “dng-ssh” Duo Network Gateway - SSH Servers “dng” Duo Network Gateway - Web Application “drawbridgenetworks” OPAQ 360 “drupal” Drupal “epic” Epic Hyperspace “f5bigip” F5 BIG-IP APM “f5firepass” F5 FirePass SSL VPN “fortinet” Fortinet FortiGate SSL VPN “greyheller” Appsian Security Platform “jira” JIRA “juniper” Juniper SSL VPN “juniperuac” Juniper UAC “keeper” Keeper Security “labtech” LabTech Software “lastpass” LastPass “ldapproxy” LDAP Proxy “macos” macOS “merakiradius” Meraki RADIUS VPN “myworkdrive” MyWorkDrive “netmotion” NetMotion Mobility “oam” Oracle Access Manager “okta” Okta “onelogin” OneLogin “openvpn” OpenVPN “openvpnas” OpenVPN Access Server “owa” Microsoft OWA “paloalto” Palo Alto SSL VPN “partner_authapi” Partner Auth API “partner_websdk” Partner WebSDK “pingfederate” PingFederate “portal” User Self-enrollment Portal (Bulk and Email enrollment) “radius” RADIUS “rdgateway” Microsoft RD Gateway “rdp” Microsoft RDP “rdweb” Microsoft RD Web “resilient” Resilient Systems “rest” Auth API “rras” Microsoft RRAS “sailpoint” SailPoint API “sailpointweb” SailPoint Web “samlidp” SAML IdP “shibboleth” Shibboleth “sonicwallsra” SonicWALL SRA SSL VPN “sophosutm” Sophos UTM “splunk” Splunk “thycotic” Thycotic Secret Server “tmg” Microsoft TMG “uag” Microsoft UAG “unix” UNIX Application “verify” Verify API “vmwareview” VMWare View “websdk” Web SDK “workday” Workday “wordpress” WordPress
trusted_device_days	Number of days to allow a user to skip second factor login. Must be between 0 and 60; 0 disables this option. Supported on the following integrations: Type Description “1password” 1Password “adfs” Microsoft ADFS “agadobe_documentcloud” SAML - Adobe Document Cloud “agasana” SAML - Asana “agaws” SAML - Amazon Web Services “agatlassian-cloud” SAML - Atlassian Cloud “agbamboohr” SAML - BambooHR “agbluejeans” SAML - BlueJeans “agbomgar” SAML - Bomgar “agbonusly” SAML - Bonusly “agbox” SAML - Box “agcanvas” SAML - Canvas “agclarizen” SAML - Clarizen “agcloudlock” SAML - CloudLock “agconfluence” SAML - Confluence “agcrashplan” SAML - CrashPlan “agdatadog” SAML - Datadog “agdesk” SAML - Desk “agdocusign” SAML - DocuSign “agdropbox” SAML - Dropbox “agegnyte” SAML - Egnyte “agevernote” SAML - Evernote “agexpensify” SAML - Expensify “agfacebook” SAML - Facebook at Work “agfreshdesk” SAML - Freshdesk “aggeneric” SAML - Service Provider “aggithub-enterprise” SAML - GitHub Enterprise “aggoogle” SAML - Google Apps “aggotomeeting” SAML - GoTo Apps “aggreenhouse” SAML - Greenhouse “aghackerone” SAML - HackerOne “agheroku” SAML - Heroku “agintacct” SAML - Intacct “agjira” SAML - JIRA “agjitbit” SAML - Jitbit “aglooker” SAML - Looker “agmarketo” SAML - Marketo “agmeraki” SAML - Meraki “agnamely” SAML - Namely “agnewrelic” SAML - New Relic “agoffice365” SAML - Office 365 “agopendns” SAML - OpenDNS “agpagerduty” SAML - PagerDuty “agremedyforce” SAML - Remedyforce “agringcentral” SAML - RingCentral “agrobin” SAML - Robin “agsalesforce” SAML - Salesforce “agsamanage” SAML - Samanage “agsharefile” SAML - ShareFile “agsignalsciences” SAML - Signal Sciences “agslack” SAML - Slack “agsmartsheet” SAML - Smartsheet “agstatuspageio” SAML - StatusPage.io “agsugarcrm” SAML - SugarCRM “agsumologic” SAML - Sumo Logic “agsyncplicity” SAML - Syncplicity “agudemy” SAML - Udemy “aguservoice” SAML - UserVoice “agwebex” SAML - Cisco WebEx “agzendesk” SAML - Zendesk “agzoom” SAML - Zoom “array” Array SSL VPN “authapi” Auth API “barracuda” Barracuda SSL VPN “bitium” Bitium “cas” CAS (Central Authentication Service) “cisco” Cisco SSL VPN “citrixcag” Citrix Access Gateway “citrixns” Citrix Gateway (formerly Citrix NetScaler) “clearpass” Aruba ClearPass “confluence” Confluence “dag” Duo Access Gateway “device-management-portal” Device Management Portal “drawbridgenetworks” Drawbridge Networks “drupal” Drupal “f5bigip” F5 BIG-IP APM “f5firepass” F5 FirePass SSL VPN “fortinet” Fortinet FortiGate SSL VPN “greyheller” Appsian Security Platform “jira” JIRA “juniper” Juniper SSL VPN “juniperuac” Juniper UAC “okta” Okta “onelogin” OneLogin “owa” Microsoft OWA “paloalto” Palo Alto SSL VPN “pingfederate” PingFederate “rdweb” Microsoft RD Web “resilient” Resilient Systems “rest” Auth API “shibboleth” Shibboleth “sonicwallsra” SonicWALL SRA SSL VPN “splunk” Splunk “websdk” Web SDK “wordpress” WordPress
username_normalization_policy	This controls whether or not usernames should be altered before trying to match them to a user account. One of: Policy Description “None” The username will be used as is. “Simple” Both “DOMAIN\username” and “username@example.com” will be normalized to “username” when logging in.

Example Response

{
  "stat": "OK",
    "response": {
        "adminapi_admins": 0,
        "adminapi_info": 0,
        "adminapi_integrations": 0,
        "adminapi_read_log": 0,
        "adminapi_read_resource": 0,
        "adminapi_settings": 0,
        "adminapi_write_resource": 0,
        "enroll_policy": "enroll",
        "greeting": "Welcome to Duo.",
        "groups_allowed": [],
        "integration_key": "DIRWIH0ZZPV4G88B37VQ",
        "ip_whitelist": [
            "192.0.2.8",
            "198.51.100.0-198.51.100.20",
            "203.0.113.0/24"
        ],
        "ip_whitelist_enroll_policy": "enforce",
        "name": "Web Application",
        "notes": "",
        "policy_key": "POHSLA8SP00LABDAD98Y",
        "secret_key": "QO4ZLqQVRIOZYkHfdPDORfcNf8LeXIbCWwHazY7",
        "self_service_allowed": false,
        "trusted_device_days": 0,
        "type": "websdk",
        "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. Requires "Grant applications" API permission.

POST /admin/v1/integrations

Parameters

Parameter	Required?	Description
name	Required	The name of the integration to create.
type	Required	The type of the integration to create. Refer to Retrieve Integrations for a list of valid values. Note that integrations of type “azure-ca” may not be created via the API.
adminapi_admins	Optional	Set to 1 to grant an Admin API integration permission for all Admins methods. Defaults to 0.
adminapi_info	Optional	If creating an Admin API integration, set this to 1 to grant it permission for all Account Info methods. Defaults to 0.
adminapi_integrations	Optional	Set to 1 to grant an Admin API integration permission for all Integrations methods. Defaults to 0.
adminapi_read_log	Optional	Set to 1 to grant an Admin API integration permission for all Logs methods. Defaults to 0.
adminapi_read_resource	Optional	Set to 1 to grant an Admin API integration permission to retrieve objects like users, phones, and hardware tokens. Defaults to 0.
adminapi_settings	Optional	Set to 1 to grant an Admin API integration permission for all Settings methods. Defaults to 0.
adminapi_write_resource	Optional	Set to 1 to grant an Admin API integration permission to create and modify objects like users, phones, and hardware tokens. Defaults to 0.
enroll_policy	Optional	What to do after an unenrolled user passes primary authentication. Refer to Retrieve Integrations for a list of valid values.
greeting	Optional	Voice greeting read before the authentication instructions to users who authenticate with a phone callback.
groups_allowed	Optional	A comma-separated list of group IDs that are allowed to authenticate with the integration. If empty, all groups are allowed. Object limits: 100 groups per integration.
ip_whitelist	Optional	CSV string of trusted IPs/Ranges. Refer to Retrieve Integrations for a list of supported integrations.
ip_whitelist_enroll_policy	Optional	What to do after a new user from a trusted IP completes primary authentication. Refer to Retrieve Integrations for a list of valid values.
networks_for_api_access	Optional	A comma-separated list of IP addresses, IP ranges, or CIDRs specifying the networks allowed to access this API integration. Only applicable to Accounts API and Admin API integrations. A given API integration may apply a network restriction to itself via API; use a different API integration to apply the network restriction, or edit the API application in the Admin Panel GUI.
notes	Optional	Description of the integration.
trusted_device_days	Optional	Number of days to allow a user to trust the device they are logging in with. Refer to Retrieve Integrations for a list of supported integrations.
self_service_allowed	Optional	Set to 1 to grant an integration permission to allow users to manage their own devices. This is only supported by integrations which allow for self service configuration.
username_normalization_policy	Optional	Policy for whether or not usernames should be altered before trying to match them to a user account. Refer to Retrieve Integrations for a list of valid values.

Response Codes

Response	Meaning
200	Success. Returns the newly created integration.
400	Invalid or missing parameters, one-to-many object limit reached, or integration already exists with the given name.
500	Other internal error.

Response Format

Same as Retrieve Integrations.

Example Response

Same as Retrieve Integration by Integration Key.

Retrieve Integration by Integration Key

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

GET /admin/v1/integrations/[integration_key]

Parameters

None.

Response Codes

Response	Meaning
200	Success.
404	No integration was found with the given integration_key.

Response Format

Same as Retrieve Integrations.

Example Response

{
  "stat": "OK",
    "response": {
        "adminapi_admins": 0,
        "adminapi_info": 0,
        "adminapi_integrations": 0,
        "adminapi_read_log": 0,
        "adminapi_read_resource": 0,
        "adminapi_settings": 0,
        "adminapi_write_resource": 0,
        "enroll_policy": "enroll",
        "greeting": "Welcome to Duo.",
        "groups_allowed": [],
        "integration_key": "DIRWIH0ZZPV4G88B37VQ",
        "ip_whitelist": [],
        "ip_whitelist_enroll_policy": "enforce",
        "name": "Web Application",
        "notes": "",
        "policy_key": "POHSL88SP00LABDAD98Y",
        "secret_key": "QO4ZLqQVRIOZYkHfdPDORfcNf8LeXIbCWwHazY7",
        "self_service_allowed": false,
        "trusted_device_days": 0,
        "type": "websdk",
        "username_normalization_policy": "None"
  }
}

Modify Integration

Change the name, enrollment policy, 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.

POST /admin/v1/integrations/[integration_key]

Parameters

Parameter	Required?	Description
name	Optional	New name for the integration.
networks_for_api_access	Optional	A comma-separated list of IP addresses, IP ranges, or CIDRs specifying the networks allowed to access this API integration. Only applicable to Accounts API and Admin API integrations. A given API integration may apply a network restriction to itself via API; use a different API integration to apply the network restriction, or edit the API application in the Admin Panel GUI.
adminapi_admins	Optional	Set to 1 to grant an Admin API integration permission for all Admins methods or 0 to remove access to them.
adminapi_info	Optional	Set to 1 to grant an Admin API integration permission for all Account Info methods or 0 to remove access to them.
adminapi_integrations	Optional	Set to 1 to grant an Admin API integration permission for all Integrations methods or 0 to remove access to them.
adminapi_read_log	Optional	Set to 1 to grant an Admin API integration permission for all Logs methods or 0 to remove access to them.
adminapi_read_resource	Optional	Set to 1 to grant an Admin API integration permission to retrieve objects like users, phones, and hardware tokens or 0 to remove access to them.
adminapi_settings	Optional	Set to 1 to grant an Admin API integration permission for all Settings methods or 0 to remove access to them.
adminapi_write_resource	Optional	Set to 1 to grant an Admin API integration permission to create and modify objects like users, phones, and hardware tokens or 0 to remove access to them.
trusted_device_days	Optional	New number of days to allow a user to trust the device they are logging in with. Refer to Retrieve Integrations for a list of supported integrations.
enroll_policy	Optional	New policy for what to do after an unenrolled user passes primary authentication. Refer to Retrieve Integrations for a list of valid values.
greeting	Optional	New voice greeting. Will be read before the authentication instructions to users who authenticate with a phone callback.
groups_allowed	Optional	A comma-separated list of group IDs that are allowed to authenticate with the integration. If set to an empty string, all groups will be allowed. Object limits: 100 groups per integration.
ip_whitelist	Optional	CSV string of trusted IPs/Ranges. Refer to Retrieve Integrations for a list of supported integrations.
ip_whitelist_enroll_policy	Optional	New policy for what to do after a new user from a trusted IP completes primary authentication. Refer to Retrieve Integrations for a list of valid values.
notes	Optional	New description of the integration.
policy_key	Optional	Specify the "Policy Key" value for a custom policy to attach it to the specified integration. Obtain a policy's key by viewing it in the Duo Admin Panel's "Policies" page or from the output of Retrieve Integrations. Leave the value blank to detach the currently attached policy from an integration.
reset_secret_key	Optional	If set to 1, resets the integration’s secret key to a new, randomly generated value. The new secret key is returned in the return value. Attempting to reset the secret key for the same Admin API integration whose integration key and secret key are used to make this call will return an error.
self_service_allowed	Optional	Set to 1 to grant an integration permission to allow users to manage their own devices. This is only supported by integrations which allow for self service configuration.
username_normalization_policy	Optional	New policy for whether or not usernames should be altered before trying to match them to a user account. Refer to Retrieve Integrations for a list of valid values.

Response Codes

Response	Meaning
200	The integration was modified successfully. Also returns the integration object (see Retrieve Integration by Integration Key).
400	Invalid or missing parameters, one-to-many object limit reached, an integration already exists with the given name, or attempting to reset the secret key used to sign this API request.
404	No integration was found with the given integration_key.
500	Other internal error.

Response Format

Same as Retrieve Integrations.

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. Requires "Grant applications" API permission.

DELETE /admin/v1/integrations/[integration_key]

Parameters

None.

Response Codes

Response	Meaning
200	The integration was deleted or did not exist.
400	Attempting to delete the integration whose secret key was used to sign this API request.

Response Format

Empty string.

Example Response

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

Endpoints

Retrieve Endpoints

Returns a paged list of endpoints. To fetch all results, call repeatedly with the offset parameter as long as the result metadata has a next_offset value. When no `limit` is specified the response is limited to 100 results. Requires "Grant read resource" API permission.

Returns results for Duo Beyond customers only.

GET /admin/v1/endpoints

Parameters

Paging Parameter	Required?	Description
limit	Optional	The maximum number of records returned. Default: 100; Max: 500
offset	Optional	The offset from 0 at which to start record retrieval. When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: 0

Response Codes

Response	Meaning
200	Success.
403	Subscription plan is not Duo Beyond.

Response Format

Key	Value
browsers	Collected information about all detected browsers on an individual endpoint.
browser_family	The web browser family.
browser_version	The web browser version.
flash_version	The Flash plugin version. If not present then “uninstalled”.
java_version	The Java plugin version. If not present then “uninstalled”.
last_used	The date and time that the endpoint's browser was last used for access, shown as a Unix timestamp.
device_identifier	The unique attribute value that identifies the endpoint in the management system. Returned for Duo Beyond customers only.
device_identifier_type	The management system attribute used to identify a unique endpoint. One of “hardware_uuid“, “fqdn“, “hardware_serial“, “device_udid“, or none. Returned for Duo Beyond customers only.
device_username	The unique attribute value that identifies the endpoint's associated user in the management system. Returned for Duo Beyond customers only.
device_username_type	The management system attribute used to identify the user associated with the unique endpoint. One of “os_username“, “upn“, “username“, “email“, or none. Returned for Duo Beyond customers only.
email	The email address, if present, of the user associated with an endpoint.
epkey	The endpoint’s unique identifier.
model	The device model of a 2FA endpoint.
os_family	The endpoint’s operating system platform.
os_version	The endpoint’s operating system version.
trusted_endpoint	Whether the endpoint is a Duo managed endpoint. One of “yes“, “no“, or “unknown“. Returned for Duo Beyond customers only.
type	The endpoint’s device class.
username	The Duo username of the user associated with an endpoint.

Example Response

{
  "stat": "OK",
  "response": [{
        "browsers": [{
            "browser_family": "Chrome",
            "browser_version": "51.0.2704.103",
            "flash_version": "22.0.0.0",
            "java_version": "uninstalled"
        },
        {
            "browser_family": "Safari",
            "browser_version": "9.1.1",
            "flash_version": "uninstalled",
            "java_version": "1.8.0.45",
            "last_used": 1474483713
        }],
        "device_identifier": "3FA47335-1976-3BED-8286-D3F1ABCDEA13",
        "device_identifier_type": "hardware_uuid",
        "device_username": "mba22915\u00e2\u0080\u0099s MacBook Air/mba22915",
        "device_username_type": "os_username",
        "email": "ejennings@example.com",
        "epkey": "EP18JX1A10AB102M2T2X",
        "model": "",
        "os_family": "Mac OS X",
        "os_version": "10.11.5",
        "trusted_endpoint": "yes",
        "type": "",
        "username": "ejennings"
    },
    {
        "browsers": [{
            {
                "browser_family": "Mobile Safari",
                "browser_version": "9.0",
                "flash_version": "uninstalled",
                "java_version": "uninstalled"
                }],
        "device_identifier": "",
        "device_identifier_type": "",
        "device_username": "",
        "device_username_type": "",
        "email": "",
        "epkey": "EP65MWZWXA10AB1027TQ",
        "model": "iPhone",
        "os_family": "iOS",
        "os_version": "9.3.3",
        "trusted_endpoint": "unknown",
        "type": "",
        "username": "mhanson"
    }],
    "stat": "OK"
}

Retrieve Endpoint by ID

Return information for an individual endpoint with epkey. Requires "Grant read resource" API permission.

GET /admin/v1/endpoints/[epkey]

Parameters

None.

Response Codes

Response	Meaning
200	Success.
403	Subscription plan is not Duo Beyond.
404	No endpoint was found with the given epkey.

Response Format

Same as Retrieve Endpoints.

Example Response

{
  "stat": "OK",
  "response": [{
        "browsers": [{
            "browser_family": "Chrome",
            "browser_version": "54.0.2840.27",
            "flash_version": "23.0.0.173",
            "java_version": "uninstalled",
            "last_used": 1474483713
        }],
        "device_identifier": "3FA47335-1976-3BED-8286-D3F1ABCDEA13",
        "device_identifier_type": "hardware_uuid",
        "device_username": "mba22915\u00e2\u0080\u0099s MacBook Air/mba22915",
        "device_username_type": "os_username",
        "email": "amoss@example.com",
        "epkey": "EP18JX1A10AB102M2T2X",
        "model": "",
        "os_family": "Mac OS X",
        "os_version": "10.11.6",
        "trusted_endpoint": "yes",
        "type": "",
        "username": "amoss"
    }],
    "stat": "OK"
}

Administrators

Retrieve Administrators

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

GET /admin/v1/admins

Parameters

Paging Parameter	Required?	Description
limit	Optional	The maximum number of records returned. Default: 100; Max: 500
offset	Optional	The offset from 0 at which to start record retrieval. When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: 0

Query Parameters

None.

Response Codes

Response	Meaning
200	Success.

Response Format

Key	Value
admin_id	The administrator’s ID.
email	The administrator’s email address.
hardtoken	Information about hardware tokens attached to the administrator, or “null” if none attached. See Retrieve Hardware Tokens for descriptions of the response values.
last_login	The last time this administrator logged in, as a UNIX timestamp, or “null” if the administrator has not logged in.
name	The administrator’s full name.
password_change_required	Either “true” if the administrator must change their password at the next login, or “false” if no password change is required.
phone	The administrator’s phone number.
restricted_by_admin_units	Is this administrator restricted by an administrative unit assignment? Either “true” or “false”. Must be set to “true” in order to add the admin to an administrative unit using the API.
role	The administrator’s role. One of: “Owner”, “Administrator”, “Application Manager”, “User Manager”, “Help Desk”, “Billing”, “Phishing Manager”, or “Read-only”. Only present in the response if the customer edition includes the Administrative Roles feature.
status	The administrator account's status. Either “Active”, “Disabled”, or “Pending Activation”.

Example Response

{
  "stat": "OK",
  "response": {
    "admin_id": "DEVKWVBJA7LO95OIBIS3",
    "email": "rscott@example.com",
    "hardtoken": {
        "serial": "1234567890",
        "token_id": "DH1TIP00LBCIH887OPSV",
        "totp_step": null,
        "type": "d1"
        },
    "last_login": 1343921403,
    "name": "Rachael Scott",
    "password_change_required": false,
    "phone": "+17345551000",
    "restricted_by_admin_units": false,
    "role": "Owner",
    "status": "Active"
  }
}

Create Administrator

Create a new administrator. Requires "Grant administrators" API permission.

POST /admin/v1/admins

Parameters

Parameter	Required?	Description
email	Required	Valid email address for the new administrator.
name	Required	Name for the new administrator.
password	Deprecated	Legacy parameter; ignored if specified. Formerly the password value for the new administrator.
password_change_required	Deprecated	This parameter may not be used when creating a new administrator, as the new admin does not have a password at creation.
phone	Optional	Phone number for the new administrator.
role	Optional	The administrator’s role. One of: “Owner”, “Administrator”, “Application Manager”, “User Manager”, “Help Desk”, “Billing”, “Phishing Manager”, or “Read-only”. The role names are case-sensitive. Defaults to “Owner” if not specified. Roles other than “Owner” are effective only if the customer edition includes the Administrative Roles feature.
restricted_by_admin_units	Optional	Is this administrator restricted by an administrative unit assignment? Either “true” or “false”. Defaults to “false” if not specified. Must be set to “true” in order to add the admin to an administrative unit using the API.
send_email	Optional	If set to “1”, the activation link and an introductory message will be emailed to the new administrator. If set to “0”, no email is sent, and the link is returned to the API method’s caller only. Default: “0”.
token_id	Optional	The token_id of the hardware token to associate with the administrator.
valid_days	Optional	Number of days before the activation link expires. Default: 7. Maximum days: 31.

Response Codes

Response	Meaning
200	Success. Returns the newly created administrator.
400	Invalid or missing parameters, or the provided email address is already in use by another administrator.

Response Format

Same as Retrieve Administrator by ID plus:

activation_url_expires

Timestamp of the activation link's expiration.

Example Response

{
  "stat": "OK",
  "response": {
    "activation_url": "https://admin-abcd1234.duosecurity.com/admins/activation/DAAR5SIVP00LYZA0WDAD/87e9b5fe47010441b5j05h2c5838fbf5",
    "activation_url_expires": 1604347975,  
    "admin_id": "DEVKWVBJA7LO95OIBIS3",
    "email": "rscott@example.com",
    "hardtoken": null,
    "last_login": null,
    "name": "Rachael Scott",
    "password_change_required": false,
    "phone": null,
    "restricted_by_admin_units": false,
    "role": "Help Desk",
    "status": "Pending Activation"
  }
}

Retrieve Administrator by ID

Return the single administrator with the administrator ID administrator_id. Requires "Grant administrators" API permission.

GET /admin/v1/admins/[administrator_id]

Parameters

None.

Response Codes

Response	Meaning
200	Success.
404	No administrator was found with the given administrator_id.

Response Format

Same as Retrieve Administrators plus:

activation_url

Link to the activation form if an activation link exists for that admin.

Example Response

{
  "stat": "OK",
  "response": {
    "activation_url": "https://admin-abcd1234.duosecurity.com/admins/activation/DAAR5SIVP00LYZA0WDAD/87e9b5fe47010441b5j05h2c5838fbf5",
    "admin_id": "DEVKWVBJA7LO95OIBIS3",
    "email": "rscott@example.com",
    "hardtoken": null,
    "last_login": null,
    "name": "Rachael Scott",
    "password_change_required": false,
    "phone": null,
    "restricted_by_admin_units": false,
    "role": "Owner",
    "status": "Pending Activation"
  }
}

Modify Administrator

Change the name, phone number, or other properties of the administrator with the administrator ID administrator_id. Requires "Grant administrators" API permission.

POST /admin/v1/admins/[administrator_id]

Parameters

Parameter	Required?	Description
name	Optional	New name for the administrator.
phone	Optional	New phone number for the administrator. If this parameter is specified it cannot be empty.
password	Deprecated	Legacy parameter; ignored if specified. Formerly the new password value for the administrator.
password_change_required	Optional	Specify “true” to require that the admin pick a new password at their next login, or “false” if no password change is required.
role	Optional	New role for the administrator. One of: “Owner”, “Administrator”, “Application Manager”, “User Manager”, “Help Desk”, “Billing”, “Phishing Manager”, or “Read-only”. The role names are case-sensitive. Roles other than “Owner” are effective only if the customer edition includes the Administrative Roles feature.
restricted_by_admin_units	Optional	Is this administrator restricted by an administrative unit assignment? Either “true” or “false”. Must be set to “true” in order to add the admin to an administrative unit using the API.
status	Optional	The administrator account status. Either “Active” or “Disabled” (case-sensitive). Administrators with the “Owner” role may not be disabled via API.
token_id	Optional	The ID of the hardware token to associate with the administrator. Specify with no value to remove any existing token assignment for that administrator.

Response Codes

Response	Meaning
200	The administrator was modified successfully. The administrator object is also returned (see Retrieve Administrator by ID).
400	Invalid or missing parameters.
404	No administrator was found with the given administrator_id.

Response Format

Same as Retrieve Administrator by ID.

Example Response

Same as Retrieve Administrator by ID.

Delete Administrator

Delete the administrator with administrator ID administrator_id from the system. Requires "Grant administrators" API permission.

DELETE /admin/v1/admins/[administrator_id]

Parameters

None.

Response Codes

Response	Meaning
200	The administrator was deleted or did not exist.

Response Format

Empty string.

Example Response

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

Reset Administrator Authentication Attempts

Clear the number of failed login attempts for the administrator with administrator_id. Re-enables an administrator who has been disabled due to too many failed authentication attempts. Requires "Grant administrators" API permission.

POST /admin/v1/admins/[administrator_id]/reset

Parameters

None.

Response Codes

Response	Meaning
200	The administrator’s authentication failure count was set to zero.
404	No administrator was found with the given administrator_id.

Response Format

Empty string.

Example Response

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

Email Activation Link to Administrator Pending Activation

Email the current activation link to the administrator pending activation with the administrator ID administrator_id. Requires "Grant administrators" API permission.

POST /admin/v1/admins/[administrator_id]/activation_link/email

Parameters

None.

Response Codes

Response	Meaning
200	An email with the activation link was sent to the admin.
400	Invalid administrator for activation.
404	Invalid administrator_id.

Response Format

Key	Value
admin_activation_id	The ID of the administrator activation link.
code	Activation code used to create this activation link and message.
email	Email address of the administrator.
expires	Timestamp of the activation link's expiration.

Example Response

{
  "stat": "OK",
  "response": {
      "admin_activation_id": "DK9PHLB5Z8NZJRFSJX4Q",
      "code": "g793cfba2b4e8684164c6b8766baad08",
      "email": "rscott@example.com",
      "expires": 1604348536
  }
}

Delete Activation Link from Administrator Pending Activation

Deletes and invalidates the current activation link from the administrator pending activation with the administrator ID administrator_id. Requires "Grant administrators" API permission.

DELETE /admin/v1/admins/[administrator_id]/activation_link

Parameters

None.

Response Codes

Response	Meaning
200	Any existing activation link was deleted and invalidated.
400	Invalid administrator for activation.
404	Invalid administrator_id.

Response Format

Same as Retrieve Administrator by ID.

Example Response

{
  "stat": "OK",
  "response": {
    "admin_id": "DEVKWVBJA7LO95OIBIS3",
    "email": "rscott@example.com",
    "hardtoken": null,
    "last_login": null,
    "name": "Rachael Scott",
    "password_change_required": false,
    "phone": null,
    "restricted_by_admin_units": false,
    "role": "Owner",
    "status": "Pending Activation"
  }
}

Create Activation Link for Administrator Pending Activation

Creates an activation link for the administrator pending activation with the administrator ID administrator_id. There must not already be an existing activation link for the admin. Requires "Grant administrators" API permission.

POST /admin/v1/admins/[administrator_id]/activation_link

Parameters

None.

Response Codes

Response	Meaning
200	Creates an activation link for the admin.
400	Invalid administrator for activation or an activation link already exists for that admin.
404	Invalid administrator_id.

Response Format

Same as Retrieve Administrator by ID.

Example Response

{
  "stat": "OK",
  "response": {
    "activation_url": "https://admin-abcd1234.duosecurity.com/admins/activation/DAAR5SIVP00LYZA0WDAD/87e9b5fe47010441b5j05h2c5838fbf5",
    "admin_id": "DEVKWVBJA7LO95OIBIS3",
    "email": "rscott@example.com",
    "hardtoken": null,
    "last_login": null,
    "name": "Rachael Scott",
    "password_change_required": false,
    "phone": null,
    "restricted_by_admin_units": false,
    "role": "Owner",
    "status": "Pending Activation"
  }
}

Create Administrator Activation Link

Create a link to the activation form for a new administrator with email address email. The administrator will not actually be created until the activation form is completed with further information (like the administrator’s name and phone number). Requires "Grant administrators" API permission.

POST /admin/v1/admins/activations

Parameters

Parameter	Required?	Description
email	Required	Email address for the new administrator. Must not already be in use by any other administrator or pending administrator activation.
admin_name	Optional	The full name of the administrator. The administrator's email will be used as the name if not specified.
admin_role	Optional	The administrator’s role. One of: “Owner”, “Administrator”, “Application Manager”, “User Manager”, “Help Desk”, “Billing”, “Phishing Manager”, or “Read-only”. The role names are case-sensitive. Defaults to “Owner” if not specified. Roles other than “Owner” are effective only if the customer edition includes the Administrative Roles feature.
send_email	Optional	If set to “1”, the activation link and an introductory message will be emailed to the new administrator. If set to “0”, no email is sent, and the link is returned to the API method’s caller only. Default: “0”.
valid_days	Optional	Number of days before the link expires. Default: 7. Maximum days: 31.

Response Codes

Response	Meaning
200	Activation link is returned (and optionally emailed).
400	Invalid or missing parameters, or email is already in use by an existing administrator or pending activation request.

Response Format

Key	Value
admin_activation_id	The ID of the administrator activation link.
admin_role	The administrator role assigned to the new admin.
code	Activation code used to create this activation link and message.
email	Email address supplied by the caller. If the activation form is completed a new administrator will be created with this email address.
email_sent	“1” if the introductory message was emailed to the new administrator; “0” otherwise.
expires	Timestamp of the activation link's expiration.
link	Link to the activation form.
message	Introductory message body.
subject	Introductory message subject.
valid_days	Number of days before the activation link expires.

Example Response

{
  "response": {
    "admin_activation_id": "DK9PHLB5Z8NZJRFSJX4Q",
    "admin_name": "Soren Ogilby",
    "admin_role": "Read-only",
    "code": "g793cfba2b4e8684164c6b8766baad08",
    "email": "sogilby@example.com",
    "email_sent": 1,
    "expires": 1550075404,
    "link": "https://admin-abcd1234.duosecurity.com/activation/g793cfba2b4e8684164c6b8766baad08",
    "message": "\nHello sogilby@example.com,\n\nYou have been added as a Duo administrator for the Acme Corp organization with the role of Read-Only. It takes about 3 minutes to set up and you will need your smartphone.\n\nClick the link below to start setting up your account. Your invitation will expire on Mon, Nov 2 at 11:02 PM UTC.\n\nhttps://admin-abcd1234.duosecurity.com/activation/g793cfba2b4e8684164c6b8766baad08\n\nRegards,\nDuo Security\n",
    "subject": "Set up your administrator account on Duo Security",
    "valid_days": 7
  },
  "stat": "OK"
}

Retrieve Pending Administrator Activations

Returns a paged list of pending administrator activations. To fetch all results, call repeatedly with the offset parameter as long as the result metadata has a next_offset value. Requires "Grant administrators" API permission.

GET /admin/v1/admins/activations

Parameters

Paging Parameter	Required?	Description
limit	Optional	The maximum number of records returned. Default: 100; Max: 500
offset	Optional	The offset from 0 at which to start record retrieval. When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: 0

Response Codes

Response	Meaning
200	A list of pending admin activations is returned.
400	Invalid paging parameters.

Response Format

Key	Value
admin_activation_id	The ID of the administrator activation link.
code	Activation code used to create this activation link and message.
email	Email address supplied by the caller. If the activation form is completed a new administrator will be created with this email address.
expires	Timestamp of the activation link's expiration.

Example Response

{
  "response": {
    "admin_activation_id": "DK9PHLB5Z8NZJRFSJX4Q",
    "code": "g793cfba2b4e8684164c6b8766baad08",
    "email": "sogilby@example.com",
    "expires": 1550075404
  },
  "stat": "OK"
}

Delete Pending Administrator Activation

Delete the pending admin activation with ID admin_activation_id from the system. Requires "Grant administrators" API permission.

DELETE /admin/v1/admins/activations/[admin_activation_id]

Parameters

None.

Response Codes

Response	Meaning
200	The pending admin activation link was deleted or did not exist.
404	Invalid admin_activation_id format.

Response Format

Empty string.

Example Response

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

Retrieve Administrator Authentication Factors

Retrieve a list of the secondary authentication methods permitted for administrator log on to the Duo Admin Panel. Requires "Grant administrators" API permission.

GET /admin/v1/admins/allowed_auth_methods

Parameters

None.

Response Codes

Response	Meaning
200	Success.

Response Format

Key	Value
hardware_token_enabled	If true, administrators may authenticate to the Duo Admin Panel with an OTP hardware token. If false, administrators may not use OTP hardware tokens.
mobile_otp_enabled	If true, administrators may authenticate to the Duo Admin Panel with a passcode generated by the Duo Mobile app. If false, administrators may not use Duo Mobile passcodes.
push_enabled	If true, administrators may authenticate to the Duo Admin Panel by approving a push request in the Duo Mobile app. If false, administrators may not approve login with Duo Push.
sms_enabled	If true, administrators may authenticate to the Duo Admin Panel with a passcode received via SMS. If false, administrators may not use SMS passcodes.
voice_enabled	If true, administrators may authenticate to the Duo Admin Panel by approving the request received via phone call. If false, administrators may not approve login with a phone call.
yubikey_enabled	If true, administrators may authenticate to the Duo Admin Panel with a Yubikey token. If false, administrators may not use Yubikey tokens.

Example Response

{
  "stat": "OK",
  "response": {
    "hardware_token_enabled": true,
    "mobile_otp_enabled": true,
    "push_enabled": true,
    "sms_enabled": false,
    "voice_enabled": false,
    "yubikey_enabled": true
  }
}

Restrict Administrator Authentication Factors

Enable or disable secondary authentication methods permitted for administrator log on to the Duo Admin Panel. When no methods are restricted Duo administrators may use any available two-factor method. Any method not explicitly set to true in the POST is disabled. Requires "Grant administrators" API permission.

POST /admin/v1/admins/allowed_auth_methods

Parameters

Parameter	Required?	Description
hardware_token_enabled	Optional, but at least one valid factor must be set to true.	If true, administrators may authenticate to the Duo Admin Panel with an OTP hardware token. If false or not specified, administrators may not use OTP hardware tokens.
mobile_otp_enabled	Optional, but at least one valid factor must be set to true.	If true, administrators may authenticate to the Duo Admin Panel with a passcode generated by the Duo Mobile app. If false or not specified, administrators may not use Duo Mobile passcodes.
push_enabled	Optional, but at least one valid factor must be set to true.	If true, administrators may authenticate to the Duo Admin Panel by approving a push request in the Duo Mobile app. If false or not specified, administrators may not approve login with Duo Push.
sms_enabled	Optional, but at least one valid factor must set to true.	If true, administrators may authenticate to the Duo Admin Panel with a passcode received via SMS. If false or not specified, administrators may not use SMS passcodes.
voice_enabled	Optional, but at least one valid factor must be set to true.	If true, administrators may authenticate to the Duo Admin Panel by approving the request received via phone call. If false or not specified, administrators may not approve login with a phone call.
yubikey_enabled	Optional, but at least one valid factor must be set to true.	If true, administrators may authenticate to the Duo Admin Panel with a Yubikey token. If false or not specified, administrators may not use Yubikey tokens.

Response Codes

Response	Meaning
200	The settings were modified successfully. The settings object is also returned (see Retrieve Administrator Authentication Factors).
400	Invalid or missing parameters. For example, no valid factor was specified.

Response Format

Same as Retrieve Administrator Authentication Factors

Example Response

Same as Retrieve Administrator Authentication Factors

Administrative Units

Retrieve Administrative Units

Returns a paged list of all administrative units if no parameters specified. To fetch all results, call repeatedly with the offset parameter as long as the result metadata has a next_offset value. Requires "Grant administrators" API permission.

Optionally specify at most one parameter to return a list of administrative units associated with the given administrator, group, or integration.

GET /admin/v1/administrative_units

Parameters

Paging Parameter	Required?	Description
limit	Optional	The maximum number of records returned. Default: 100; Max: 500
offset	Optional	The offset from 0 at which to start record retrieval. When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: 0

Query Parameter	Required?	Description
admin_id	Optional	A Duo administrator's admin_id.
group_id	Optional	A Duo group's group_id.
integration_key	Optional	The integration_key for a Duo integration.

Response Codes

Response	Meaning
200	Success.
404	No administrative unit was found with the given admin_id, group_id, or integration_key.

Response Format

Key	Value
admin_unit_id	The administrative unit's unique ID.
name	The administrative unit's name.
description	The administrative unit's description.
restrict_by_groups	Does the administrative unit specify groups? Either “true” or “false”.
restrict_by_integrations	Does the administrative unit specify integrations? Either “true” or “false”.

Example Response

{
  "stat": "OK",
  "response": [{
    "admin_unit_id": "AUT0HJ753KH67HGF4S7H",
    "description": "Acme Corp Europe, Middle East, and Africa",
    "name": "Acme EMEA",
    "restrict_by_groups": true,
    "restrict_by_integrations": true
    },
    {
    "admin_unit_id": "AUDJ753KH6Z252X1B2B4",
    "description": "Acme Corp United States",
    "name": "Acme USA",
    "restrict_by_groups": true,
    "restrict_by_integrations": true
  }]
}

Retrieve Administrative Unit Details

Returns details for a single administrative unit with admin_unit_id. Requires "Grant administrators" API permission.

GET /admin/v1/administrative_units/[admin_unit_id]

Parameters

None.

Response Codes

Response	Meaning
200	Success.
404	No administrative unit was found with the given admin_unit_id.

Response Format

Key	Value
admin_unit_id	The administrative unit's unique ID.
name	The administrative unit's name.
description	The administrative unit's description.
restrict_by_groups	Does the administrative unit specify groups? Either “true” or “false”.
restrict_by_integrations	Does the administrative unit specify integrations? Either “true” or “false”.
admins	The administrators assigned to the new administrative unit, listed by admin_id.
groups	The groups assigned to the new administrative unit, listed by group_id.
integrations	The integrations assigned to the new administrative unit, listed by integration_key.

Example Response

{
  "stat": "OK",
  "response": [{
    "admin_unit_id": "AUTU3AA76HG76K9GPFJ2",
    "admins": [
      "DEA76HG76K45TQHBMFI4"
    ],
    "description": "Acme Networking and VPN Admins",
    "groups": [],
    "integrations": [
      "DIBA76HEQMHRWA76KSSH"
    ],
    "name": "Acme Net Admins",
    "restrict_by_groups": false,
    "restrict_by_integrations": true
  }
}

Add Administrative Unit

Add a new administrative unit with specified administrators, groups, or other parameters. Requires "Grant administrators" API permission.

POST /admin/v1/administrative_units

Parameters

Parameter	Required?	Description
name	Required	The name of the new administrative unit. Must be unique amongst all administrative units.
description	Required	A description of the new administrative unit.
restrict_by_groups	Required	Does the new administrative unit specify groups? Default: “false”.
restrict_by_integrations	Optional	Does the new administrative unit specify integrations? Default: “false”.
admins	Optional	One or more admin_id values to assign administrators to the new administrative unit. The administrator user must have restricted_by_admin_units set to “true” before attempting to assign them to an administrative unit via the API.
groups	Optional	One or more group_id values to assign groups to the new administrative unit.
integrations	Optional	One or more integration_key values to assign integrations to the new administrative unit.

Response Codes

Response	Meaning
200	The administrative unit was created. The newly created unit is also returned.
400	Invalid or missing parameter(s), or administrative unit already exists with the given name.

Response Format

Same as Retrieve Administrative Unit Details.

Modify Administrative Unit

Change the name, description, assigned administrators, groups, and/or integrations of the administrative unit with admin_unit_id. Requires "Grant administrators" API permission.

POST /admin/v1/administrative_units/[admin_unit_id]

Parameters

Parameter	Required?	Description
name	Optional	The new name of the administrative unit. Must be unique amongst all administrative units.
description	Optional	An updated description of the administrative unit.
restrict_by_groups	Optional	Change whether the administrative unit specifies groups. Default: “false”.
restrict_by_integrations	Optional	Change whether the administrative unit specifies integrations. Default: “false”.
admins	Optional	One or more admin_id values to assign additional administrators to the administrative unit. The administrator user must have restricted_by_admin_units set to “true” before attempting to assign them to an administrative unit via the API.
groups	Optional	One or more group_id values to assign additional groups to the administrative unit.
integrations	Optional	One or more integration_key values to assign additional integrations to the administrative unit.

Response Codes

Response	Meaning
200	The administrative unit was modified. Also returns unit details.
400	Invalid parameter(s), or an administrative unit with the specified admin_unit_id does not exist.

Response Format

Same as Retrieve Administrative Unit Details.

Add Administrator to Administrative Unit

Assign the administrator with admin_id to the administrative unit with admin_unit_id. The administrator user must have restricted_by_admin_units set to “true” before attempting to assign them to an administrative unit via the API. Requires "Grant administrators" API permission.

POST /admin/v1/administrative_units/[admin_unit_id]/admin/[admin_id]

Parameters

None.

Response Codes

Response	Meaning
200	The administrative unit was modified. Also returns unit details.
400	Invalid admin_unit_id or admin_id, or the restricted_by_admin_units value is "false" for that administrator.

Response Format

Same as Retrieve Administrative Unit Details.

Remove Administrator from Administrative Unit

Unassign the administrator with admin_id from the administrative unit with admin_unit_id. The administrator user will still have restricted_by_admin_units set to "true", and if the admin is not assigned to any other admin unit they will not be able to view any users or integrations. Be sure to change the value of restricted_by_admin_units to "false" to permit that admin to view all users and integrations. Requires "Grant administrators" API permission.

DELETE /admin/v1/administrative_units/[admin_unit_id]/admin/[admin_id]

Parameters

None.

Response Codes

Response	Meaning
200	The administrative unit was modified. Also returns unit details.
400	Invalid admin_unit_id or admin_id.

Response Format

Same as Retrieve Administrative Unit Details.

Add Group to Administrative Unit

Assign the group with group_id to the administrative unit with admin_unit_id. Requires "Grant administrators" API permission.

POST /admin/v1/administrative_units/[admin_unit_id]/group/[group_id]

Parameters

None.

Response Codes

Response	Meaning
200	The administrative unit was modified. Also returns unit details.
400	Invalid admin_unit_id or group_id.

Response Format

Same as Retrieve Administrative Unit Details.

Remove Group from Administrative Unit

Unassign the group with group_id from the administrative unit with admin_unit_id. Requires "Grant administrators" API permission.

DELETE /admin/v1/administrative_units/[admin_unit_id]/group/[group_id]

Parameters

None.

Response Codes

Response	Meaning
200	The administrative unit was modified. Also returns unit details.
400	Invalid admin_unit_id or group_id.

Response Format

Same as Retrieve Administrative Unit Details.

Add Integration to Administrative Unit

Assign the integration with integration_key to the administrative unit with admin_unit_id. Requires "Grant administrators" API permission.

POST /admin/v1/administrative_units/[admin_unit_id]/integration/[integration_key]

Parameters

None.

Response Codes

Response	Meaning
200	The administrative unit was modified. Also returns unit details.
400	Invalid admin_unit_id or integration_key.

Response Format

Same as Retrieve Administrative Unit Details.

Remove Integration from Administrative Unit

Unassign the integration with admin_id from the administrative unit with admin_unit_id. Requires "Grant administrators" API permission.

DELETE /admin/v1/administrative_units/[admin_unit_id]/integration/[integration_key]

Parameters

None.

Response Codes

Response	Meaning
200	The administrative unit was modified. Also returns unit details.
400	Invalid admin_unit_id or integration_key.

Response Format

Same as Retrieve Administrative Unit Details.

Delete Administrative Unit

Delete the administrative unit with admin_unit_id from the system. Requires "Grant administrators" API permission.

DELETE /admin/v1/administrative_units/[admin_unit_id]

Parameters

None.

Response Codes

Response	Meaning
200	The administrative unit was deleted or did not exist.

Response Format

Empty string.

Example Response

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

Logs

Authentication Logs

Returns a paged list of authentication log events ranging from the last 180 days up to as recently as two minutes before the API request. To fetch all results, call repeatedly with the next_offset paging parameter as long as the result metadata has next_offset values. Requires "Grant read log" API permission.

There is an intentional two minute delay in availability of new authentications in the API response. Duo operates a large scale distributed system, and this two minute buffer period ensures that calls will return consistent results. Querying for results more recent than two minutes will return as empty.

We recommend requesting logs no more than once per minute.

The v2 handler provides new filtering and querying capabilities unavailable in the legacy v1 handler. This includes the ability to filter on users, groups, applications, authentication results, factors, and time ranges.

GET or POST /admin/v2/logs/authentication

Parameters

Paging Parameter	Required?	Allow Multiple?	Description
limit	Optional	No	The maximum number of records returned. Default: 100; Max: 1000
next_offset	Optional	Yes	The offset at which to start record retrieval. This value is provided in the metadata in the form of a 13 character date string in milliseconds and the event txid. Both of these values must be provided when used, separated by a comma (e.g. next_offset=1547486297000,5bea1c1e-612c-4f1d-b310-75fd31385b15). When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: None
sort	Optional	No	The order in which to return records. One of: Value Description ts:asc Return logs in chronological order. ts:desc Return logs in reverse chronological order.

Query Parameter	Required?	Allow Multiple?	Description
mintime	Required	No	Return records that have a 13 character Unix timestamp in milliseconds of mintime or later. This value must be strictly less then maxtime.
maxtime	Required	No	Return records that have a 13 character Unix timestamp in milliseconds of maxtime or earlier. This value must be strictly greater then mintime.
applications	Optional	Yes. Multiple values create an OR query.	An integration's integration_key or the key value for an application returned in the authentication log output. Default: Return logs for all applications.
users	Optional	Yes. Multiple values create an OR query.	A user's user_id or the key value for a user returned in the authentication log output. Default: Return logs for all users.
event_types	Optional	Yes. Multiple values create an OR query.	The type of authentication event. One of: Value Description authentication Return events for authentication attempts. enrollment Return events related to a user completing Duo's inline enrollment.
factors	Optional	Yes. Multiple values create an OR query.	The factor or method used for an authentication attempt. One of: Value Description duo_push Return events where the authentication factor was “Duo Push“. phone_call Return events where the authentication factor was a phone call. u2f_token Return events where the authentication factor was a U2F token. hardware_token Return events where the authentication factor was a hardware token passcode. bypass_code Return events where the authentication factor was a bypass code. sms_passcode Return events where the authentication factor was an SMS passcode. duo_mobile_passcode Return events where the authentication factor was a passcode generated by “Duo Mobile“. yubikey_code Return events where the authentication factor was a Yubikey OTP token passcode. passcode Return events where the authentication factor was a passcode not identified as another known type. digipass_go_7_token Return events where the authentication factor was a Digipass GO 7 token purchased from Duo. WebAuthn Credential Return events where the authentication factor was a WebAuthn authenticator, like a FIDO2 security key or Touch ID. not_available Return events where the authentication factor is not available. sms_refresh Return events where the user requested a refresh batch of SMS passcodes. remembered_device Return events where the authentication factor was the remembered device token from a previous authentication success. trusted_network Return events where the effective authentication factor was an authorized network.
groups	Optional	Yes. Multiple values create an OR query.	A group's group_id or the key value for a group returned in the authentication log output. Default: Return logs for all groups.
phone_numbers	Optional	Yes. Multiple values create an OR query.	A phone's number as returned in the authentication log output. If the phone has been given a text name then both are returned in the format name (number). Default: Return logs for all phone numbers used.
reasons	Optional	Yes. Multiple values create an OR query.	The reason associated with an authentication attempt. One of: Value Description user_marked_fraud Return events where authentication was denied because the end user explicitly marked “fraudulent“. deny_unenrolled_user Return events where authentication was denied because of the following policy: “deny not enrolled users“. error Return events where authentication was denied because of an error. locked_out Return events generated by users that are locked out. user_disabled Return events where authentication was denied because the user was disabled. user_cancelled Return events where authentication was denied because the end user cancelled the request. invalid_passcode Return events where authentication was denied because the passcode was invalid. no_response Return events where authentication was denied because there was no response from the user. no_keys_pressed Return events where authentication was denied because no keys were pressed to accept the auth. call_timed_out Return events where authentication was denied because the call was not answered or call authentication timed out for an indeterminate reason. location_restricted Return events where authentication was denied because the end user's location was restricted. factor_restricted Return events where authentication was denied because the authentication method used was not allowed. platform_restricted Return events where authentication was denied because the access platform was not allowed. version_restricted Return events where authentication was denied because the software version was not allowed. rooted_device Return events where authentication was denied because the approval device was rooted. no_screen_lock Return events where authentication was denied because the approval device does not have screen lock enabled. touch_id_disabled Return events where authentication was denied because the approval device's biometrics (fingerprint, Face ID or Touch ID) is disabled. no_disk_encryption Return events where authentication was denied because the approval device did not have disk encryption enabled. anonymous_ip Return events where authentication was denied because the authentication request came from an anonymous IP address. out_of_date Return events where authentication was denied because the software was out of date. denied_by_policy Return events where authentication was denied because of a policy. software_restricted Return events where authentication was denied because of software restriction. no_duo_certificate_present Return events where authentication was denied because there was no Duo certificate present. user_provided_invalid_certificate Return events where authentication was denied because an invalid management certificate was provided. could_not_determine_if_endpoint_was_trusted Return events where authentication was denied because it could not be determined if the endpoint was trusted. invalid_management_certificate_collection_state Return events where authentication was denied because of an invalid management certificate collection state. no_referring_hostname_provided Return events where authentication was denied because no referring hostname was provided. invalid_referring_hostname_provided Return events where authentication was denied because an invalid referring hostname was provided. no_web_referer_match Return events where authentication was denied because an invalid referring hostname did not match an application's hostnames list. endpoint_failed_google_verification Return events where authentication was denied because the endpoint failed Google verification. endpoint_is_not_trusted Return events where authentication was denied because the endpoint was not trusted. invalid_device Return events where authentication was denied because the device was invalid. anomalous_push Return events where authentication was denied because of an anomalous push. endpoint_is_not_in_management_system Return events where authentication was denied because the endpoint is not in a management system. no_activated_duo_mobile_account Return events where authentication was denied because the end user does not have an activated Duo Mobile app account. allow_unenrolled_user Return events where authentication was successful because of the following policy: “allow not enrolled users“. bypass_user Return events where authentication was successful because a bypass code was used. trusted_network Return events where authentication was successful because the end user was on a trusted network. remembered_device Return events where authentication was successful because the end user was on a remembered device. trusted_location Return events where authentication was successful because the end user was in a trusted location. user_approved Return events where authentication was successful because the end user approved the authentication request. valid_passcode Return events where authentication was successful because the end user used a valid passcode. allowed_by_policy Return events where authentication was successful because of a policy. allow_unenrolled_user_on_trusted_network Return events where authentication was successful because the unenrolled user's access device was on an authorized network. user_not_in_permitted_group Return events where authentication was denied because the user did not belong to one of the Permitted Groups specified in the application's settings. Default: Return logs for any result. Filtering on all values is equivalent to the default.
results	Optional	Yes. Multiple values create an OR query.	The result of an authentication attempt. One of: Value Description success Return “successful“ authentication events. denied Return “denied“ authentication events. fraud Return “fraudulent“ authentication events. Default: Return logs for any result. Filtering on all values is equivalent to the default.
registration_id	Optional	Yes. Multiple values create an OR query.	A FIDO U2F token's registration_id as returned in the authentication log output. Default: Return logs for all U2F tokens used.
token_id	Optional	Yes. Multiple values create an OR query.	A hardware OTP token's token_id as returned in the authentication log output. Default: Return logs for all OTP tokens used.
webauthnkey	Optional	Yes. Multiple values create an OR query.	A WebAuthn security key's webauthnkey as returned in the authentication log output. Default: Return logs for security keys used.

Response Codes

Response	Meaning
200	Success.
400	Invalid or missing parameters or mintime is after the maxtime.

Response Format

Key	Value
access_device	Browser, plugin, and operating system information for the endpoint used to access the Duo-protected resource. Values present only when the application accessed features Duo’s inline browser prompt. This information is available to Duo Beyond and Duo Access plan customers. browser The web browser used for access. browser_version The browser version. flash_version The Flash plugin version used, if present, otherwise “uninstalled“. hostname The hostname, if present, otherwise “null“. ip The access device's IP address, if present, otherwise “null“. is_encryption_enabled Reports the disk encryption state as detected by the Duo Device Health app. One of “true“, “false“, or “unknown“. is_firewall_enabled Reports the firewall state as detected by the Duo Device Health app. One of “true“, “false“, or “unknown“. is_password_set Reports the system password state as detected by the Duo Device Health app. One of “true“, “false“, or “unknown“. java_version The Java plugin version used, if present, otherwise “uninstalled“. location The GeoIP location of the access device, if available. The response may not include all location parameters. city The city name. country The country code. state The state, county, province, or prefecture. os The device operating system name. os_version The device operating system version. security_agents Reports the security agents present on the endpoint as detected by the Duo Device Health app.
alias	The username alias used to log in. No value if the user logged in with their username instead of a username alias.
application	Information about the application accessed. key The application's integration_key. name The application's name.
auth_device	Information about the device used to approve or deny authentication. ip The IP address of the authentication device. location The GeoIP location of the authentication device, if available. The response may not include all location parameters. city The city name. country The country code. state The state, county, province, or prefecture. name The name of the authentication device.
email	The email address of the user, if known to Duo, otherwise none.
event_type	The type of activity logged. one of: “authentication” or “enrollment”.
factor	The authentication factor. One of: “phone_call”, “passcode”, “yubikey_passcode”, “digipass_go_7_token”, “hardware_token”, “duo_mobile_passcode”, “bypass_code”, “sms_passcode”, “sms_refresh”, “duo_push”, “u2f_token”, “remembered_device”, or “trusted_network'”.
isotimestamp	ISO8601 timestamp of the event.
ood_software	If authentication was denied due to out-of-date software, shows the name of the software, i.e. “Chrome”, “Flash”, etc. No value if authentication was successful or authentication denial was not due to out-of-date software.
reason	Provide the reason for the authentication attempt result. If result is “SUCCESS” then one of: “allow_unenrolled_user”, “allowed_by_policy”, “allow_unenrolled_user_on_trusted_network”, “bypass_user”, “remembered_device”, “trusted_location”, “trusted_network”, “user_approved”, “valid_passcode”. If result is “FAILURE” then one of: “anonymous_ip”, “anomalous_push”, “could_not_determine_if_endpoint_was_trusted”, “denied_by_policy”, “denied_network”, “deny_unenrolled_user”, “endpoint_is_not_in_management_system”, “endpoint_failed_google_verification”, “endpoint_is_not_trusted”, “factor_restricted”, “invalid_management_certificate_collection_state”, “invalid_device”, “invalid_passcode”, “invalid_referring_hostname_provided”, “location_restricted”, “locked_out”, “no_activated_duo_mobile_account”, “no_disk_encryption”, “no_duo_certificate_present”, “touchid_disabled”, “no_referring_hostname_provided”, “no_response”, “no_screen_lock”, “no_web_referer_match”, “out_of_date”, “platform_restricted”, “rooted_device”, “software_restricted”, “user_cancelled”, “user_disabled”, “user_mistake”, “user_not_in_permitted_group”, “user_provided_invalid_certificate”, or “version_restricted”. If result is “ERROR” then: “error”. If result is “FRAUD” then: “user_marked_fraud”.
result	The result of the authentication attempt. One of: “SUCCESS”, “FAILURE”, “ERROR”, or “FRAUD”.
timestamp	Unix timestamp of the event.
txid	The transaction ID of the event.
user	Information about the authenticating user. groups Duo group membership information for the user. key The user's user_id. name The user's username.

Example Response

200 OK
{
    "response": {
        "authlogs": [
            {
                "access_device": {
                    "browser": "Chrome",
                    "browser_version": "67.0.3396.99",
                    "flash_version": "uninstalled",
                    "hostname": "null",
                    "ip": "169.232.89.219",
                    "is_encryption_enabled": true,
                    "is_firewall_enabled": true,
                    "is_password_set": true,
                    "java_version": "uninstalled",
                    "location": {
                        "city": "Ann Arbor",
                        "country": "United States",
                        "state": "Michigan"
                    },
                    "os": "Mac OS X",
                    "os_version": "10.14.1",
                    "security_agents": []
                },
                "alias": "",
                "application": {
                    "key": "DIY231J8BR23QK4UKBY8",
                    "name": "Microsoft Azure Active Directory"
                },
                "auth_device": {
                    "ip": "192.168.225.254",
                    "location": {
                        "city": "Ann Arbor",
                        "country": "United States",
                        "state": "Michigan"
                    },
                    "name": "My iPhone X (734-555-2342)"
                },
                "email": "narroway@example.com",
                "event_type": "authentication",
                "factor": "duo_push",
                "isotimestamp": "2020-02-13T18:56:20.351346+00:00",
                "ood_software": "null",
                "reason": "user_approved",
                "result": "success",
                "timestamp": 1581620180,
                "trusted_endpoint_status": "not trusted",
                "txid": "340a23e3-23f3-23c1-87dc-1491a23dfdbb",
                "user": {
                    "groups": [
                        "Duo Users",
                        "CorpHQ Users"
                    ],
                    "key": "DU3KC77WJ06Y5HIV7XKQ",
                    "name": "narroway@example.com"
                }
            },
         ],
        "metadata": {
            "next_offset": [
                "1532951895000",
                "af0ba235-0b33-23c8-bc23-a31aa0231de8"
            ],
            "total_objects": 1
        }
    },
    "stat": "OK"
}

Authentication Logs (Legacy v1)

The v2 authentication logs endpoint provides new filtering and querying capabilities unavailable in the legacy v1 handler, like the ability to filter on users, groups, applications, authentication results, factors, and time ranges. Consider migrating to the new handler.

Returns a list of authentication log events ranging from the last 180 days up to as recently as two minutes before the API request. There is an intentional two minute delay in availability of new authentications in the API response. Duo operates a large scale distributed system, and this two minute buffer period ensures that calls will return consistent results. Querying for results more recent than two minutes will return as empty. Requires "Grant read log" API permission.

The 1000 earliest events will be returned; you may need to call this multiple times with mintime to page through the entire log. Note that more or fewer than 1000 events may be returned depending on how many actual events exist for the specified mintime.

We recommend requesting logs no more than once per minute.

GET /admin/v1/logs/authentication

Parameters

Parameter	Required?	Description
mintime	Optional	Only return records that have a Unix timestamp of mintime or later. Use mintime+1 to avoid receiving duplicate data.

Response Codes

Response	Meaning
200	Success.

Response Format

Key	Value
access_device	Browser, plugin, and operating system information for the endpoint used to access the Duo-protected resource. Values present only when the application accessed features Duo’s inline browser prompt. This information is available to Duo Beyond and Duo Access plan customers. browser The web browser used for access. browser_version The browser version. flash_version The Flash plugin version used, if present, otherwise “uninstalled“. java_version The Java plugin version used, if present, otherwise “uninstalled“. os The device operating system name. os_version The device operating system version. trusted_endpoint_status Shows whether the endpoint is a Duo managed endpoint. One of “trusted“, “not trusted“, “unknown“, or “error“. Returned for Duo Beyond customers only.
alias	The username alias used to log in. No value if the user logged in with their username instead of a username alias.
device	Device used to authenticate, if present, otherwise none.
email	The email address of the user, if known to Duo, otherwise none.
factor	The authentication factor. One of: “Bypass Code”, “Digipass GO 7 Token”, “Duo Mobile Passcode”, “Duo Push”, “Passcode”, “Phone Call”, “Hardware Token”, “Remembered Device”, “Security Key (WebAuthn)”, “SMS Passcode”, “SMS Refresh”, “Touch ID (WebAuthn)”, “Trusted Network”, “U2F Token”, or “Yubikey Passcode”.
integration	The integration name.
ip	The IP address that this request originated from.
isotimestamp	ISO8601 timestamp of the event.
location	The GeoIP location from which the user authenticated, if available. The response may not include all location parameters.
city	The city name.
state	The state, county, province, or prefecture.
country	The country code.
new_enrollment	“True” if the user enrolled a new device at the authentication prompt; “False” if authenticated with a previously enrolled device.
ood_software	If authentication was denied due to out-of-date software, shows the name of the software, i.e. “Chrome”, “Flash”, etc. No value if authentication was successful or authentication denial was not due to out-of-date software.
reason	Provide the reason for the authentication attempt result. If result is “SUCCESS” then one of: “Allow unenrolled user”, “Allowed by policy”, “Bypass user”, “Remembered device”, “Trusted location”, “Trusted network”, “User approved”, “Valid passcode”. If result is “FAILURE” then one of: “Anonymous IP”, “Anomalous push”, “Call timed out”, “Couldn't determine if endpoint was trusted”, “Denied by policy”, “Deny unenrolled user”, “Endpoint is not in Management System”, “Factor restricted”, “Invalid device”, “Invalid passcode”, “Location restricted”, “Locked out”, “No Duo certificate present”, “No response”, “No disk encryption”, “No fingerprint”, “No screen lock”, “Out of date”, “Platform restricted”, “Rooted device”, “Software Restricted”, “User cancelled”, “User is disabled”, “User mistake”, “User provided an invalid certificate”, or “Version restricted”. If result is “ERROR” then: “Error”. If result is “FRAUD” then: “User marked fraud”.
result	The result of the authentication attempt. One of: “SUCCESS”, “FAILURE”, “ERROR”, or “FRAUD”.
timestamp	Unix timestamp of the event.
username	The authenticating user’s username.

Example Response

{
  "stat": "OK",
  "response": [{
      "access_device": {
           "browser": "Chrome",
           "browser_version": "56.0.2924.87",
           "flash_version": "25.0.0.0",
           "java_version": "1.8.0.92",
           "os": "Mac OS X",
           "os_version": "10.11"
           "trusted_endpoint_status": "trusted"
      },
      "alias": "john.smith",
      "device": "503-555-1000",
      "email": "jsmith@example.com",
      "factor": "Duo Push",
      "integration": "Acme Intranet",
      "ip": "192.168.0.1",
      "isotimestamp": "2020-02-13T18:56:20.351346+00:00",
      "ood_software": ""
      "location": {
           'city': 'Ann Arbor',
           'state': 'Michigan',
           'country': 'US'
      },
      "new_enrollment": false,
      "reason": "User Approved",
      "result": "SUCCESS",
      "timestamp": 1581620180,
      "username": "jsmith",

  }]
}

Administrator Logs

Returns a list of administrator log events. Only the 1000 earliest events will be returned; you may need to call this multiple times with mintime to page through the entire log. Requires "Grant read log" API permission.

We recommend requesting logs no more than once per minute.

GET /admin/v1/logs/administrator

Parameters

Parameter	Required?	Description
mintime	Optional	Only return records that have a Unix timestamp after mintime. This can help to avoid fetching records that have already been retrieved.

Response Codes

Response	Meaning
200	Success.

Response Format

Key	Value
action	The type of change that was performed. Possible values: Type Description “activation_create_link” New admin activation link created “activation_delete_link” Admin activation link deleted “activation_send_link” Emailed activation link to admin “accountsapi_request_ip_denied” Accounts API request blocked due to IP restriction “ad_sync_begin” AD Sync started “ad_sync_by_user_begin” AD Sync of individual user started “ad_sync_by_user_finish” AD Sync of individual user completed “ad_sync_config_download” AD Sync configuration download “ad_sync_failed” AD Sync failed “ad_sync_finish” AD Sync completed “admin_2fa_error” Issue completing secondary authentication “admin_account_switch” Administrator switched to this account from another Duo account “admin_activation_create” An admin activation link was created “admin_activation_delete” An admin activation link was deleted “admin_activates_duo_push” Administrator activates an admin's 2FA device for Duo Push “admin_create” Added administrator “admin_delete” Deleted administrator “admin_factor_restrictions_update” Modified admin factor restrictions “admin_login” Logged in “admin_login_error” Issue completing primary password or SAML authentication “admin_reactivates_duo_push” Administrator reactivates an admin's 2FA device for Duo Push “admin_reset_password” Administrator changed password via emailed reset link “admin_send_reset_password_email” Password reset email sent to administrator “admin_update” Modified administrator “adminapi_request_ip_denied” Admin API request blocked due to IP restriction “azure_directory_create” Azure Directory created “azure_directory_update” Azure Directory modified “azure_directory_delete” Azure Directory deleted “azure_sync_begin” Full Azure Sync started “azure_sync_by_user_begin” Azure Sync of individual user started “azure_sync_by_user_finish” Azure Sync of individual user completed “azure_sync_finish” Full Azure Sync completed “azure_sync_fail” Azure Sync failed “bypass_create” Bypass code created “bypass_delete” Bypass code deleted “bypass_view” Viewed a user's bypass code “create_child_customer” Created child customer “credits_update” Added telephony credits “customer_update” Modified settings “delete_child_customer” Deleted child customer “directory_create” Added directory “directory_delete” Deleted directory “directory_groups_update” Modified directory groups “directory_update” Modified directory “edition_update” Update edition “feature_add” Added feature “feature_delete” Deleted feature “group_create” Added group “group_delete” Deleted group “group_update” Updated group “hardtoken_create” Created hardware tokens “hardtoken_delete” Deleted hardware token “hardtoken_resync” Resynchronized hardware token “hardtoken_update” Modified hardware token “integration_create” Added application “integration_delete” Deleted application “integration_group_policy_add” Add application group policy “integration_group_policy_remove” Remove application group policy “integration_policy_assign” Assign application policy “integration_policy_unassign” Unassign application policy “integration_skey_view” Viewed secret key “integration_update” Modified application “openldap_sync_begin” OpenLDAP Sync started “openldap_sync_by_user_begin” OpenLDAP Sync of individual user started “openldap_sync_by_user_finish” OpenLDAP Sync of individual user completed “openldap_sync_config_download” OpenLDAP Sync configuration download “openldap_sync_failed” OpenLDAP Sync failed “openldap_sync_finish” OpenLDAP Sync completed “phone_associate” Associated phone “phone_create” Added phone “phone_delete” Deleted phone “phone_disassociate” Disassociated phone “phone_update” Modified phone “policy_create” Added policy “policy_delete” Deleted policy “policy_update” Modified policy “regen_mobile” Generated a new Duo Mobile Activation Code “regen_sms” Generated new SMS passcodes and sent them to a phone “resend_enroll_codes” Resend all enroll codes “send_enroll_code” Send an enroll code “u2ftoken_create” Created U2F token “u2ftoken_delete” Deleted U2F token “user_bulk_activate” Bulk mobile activation sent “user_bulk_enroll” Bulk enrollment “user_create” Added user “user_delete” Deleted user “user_import” Imported users “user_pending_delete” Marked user for deletion “user_restore” Restored deleted user “user_update” Modified user
description	String detailing what changed, either as free-form text or serialized JSON. When the description contains JSON it may be either a serialized object or a serialized array of objects. Each key in the object(s) corresponds to a property that was changed. This JSON is intended only to summarize the change, not to be de-serialized. The first example below is for a “user_update” action. The object that changed was a user whose Duo username is “jsmith”. The change saved new values for the user’s “notes” and “realname” fields, overwriting the previous values if any were set. They correspond to the similarly named fields in the Modify User call in the Admin API and the User Details page in the Admin Panel. The second example shows an “admin_login_error” action. The administrator's login attempt failed because the admin attempted to use SSO but, as indicated by the “error” in the description, SAML login is disabled for administrators on that account.
isotimestamp	ISO8601 timestamp of the event.
object	The object that was acted on. For example: “jsmith” (for users), “(555) 713-6275 x456” (for phones), or “HOTP 8-digit 123456” (for tokens).
timestamp	Unix timestamp of the event.
username	The full name of the administrator who performed the action in the Duo Admin Panel. If the action was performed with the API this will be “API”. Automatic actions like deletion of inactive users have “System” for the username. Changes synchronized from Directory Sync will have a username of the form (example) “AD Sync: name of directory.”

Example Responses

{
  "stat": "OK",
  "response": [{
      "action": "user_update",
      "description": "{\"notes\": \"Joe asked for their nickname to be displayed instead of Joseph.\", \"realname\": \"Joe Smith\"}",
      "isotimestamp": "2020-01-24T15:09:42+00:00",
      "object": "jsmith",
      "timestamp": 1579878582,
      "username": "admin"
  }]
}

{
  "stat": "OK",
  "response": [{
      "action": "admin_login_error",
      "description": "{\"ip_address\": \"10.1.23.116\", \"error\": \"SAML login is disabled\", \"email\": \"narroway@example.com\"}",
      "isotimestamp": "2020-01-23T16:18:58+00:00",
      "object": null,
      "timestamp": 1579796338,
      "username": ""
  }]
}

Telephony Logs

Returns a list of telephony log events. Only the 1000 earliest events will be returned; you may need to call this multiple times with mintime to page through the entire log. Requires "Grant read log" API permission.

We recommend requesting logs no more than once per minute.

GET /admin/v1/logs/telephony

Parameters

Parameter	Required?	Description
mintime	Optional	Only return records that have a Unix timestamp after mintime. This can help to avoid fetching records that have already been retrieved.

Response Codes

Response	Meaning
200	Success.

Response Format

Key	Value
timestamp	Unix timestamp of the event.
context	How this telephony event was initiated. One of: “administrator login”, “authentication”, “enrollment”, or “verify”.
credits	How many telephony credits this event cost.
isotimestamp	ISO8601 timestamp of the event.
phone	The phone number that initiated this event.
type	The event type. Either “sms” or “phone”.

Example Response

{
  "stat": "OK",
  "response": [{
      "context": "authentication",
      "credits": 1,
      "isotimestamp": "2020-03-20T15:38:12+00:00",
      "phone": "+15035550100",
      "timestamp": 1584718692,
      "type": "sms"
  }]
}

Offline Enrollment Logs

Returns a list of Duo Authentication for Windows Logon offline enrollment events ranging from the last 180 days up to as recently as two minutes before the API request. There is an intentional two minute delay in availability of new authentications in the API response. Duo operates a large scale distributed system, and this two minute buffer period ensures that calls will return consistent results. Querying for results more recent than two minutes will return as empty. Requires "Grant read log" API permission.

The 1000 earliest events will be returned; you may need to call this multiple times with mintime to page through the entire log. Note that more or fewer than 1000 events may be returned depending on how many actual events exist for the specified mintime.

We recommend requesting logs no more than once per minute.

GET /admin/v1/logs/offline_enrollment

Parameters

Parameter	Required?	Description
mintime	Optional	Only return records that have a Unix timestamp of mintime or later. Use mintime+1 to avoid receiving duplicate data.

Response Codes

Response	Meaning
200	Success.

Response Format

Key	Value
action	The offline enrollment operation. One of “o2fa_user_provisioned”, “o2fa_user_deprovisioned”, or “o2fa_user_reenrolled”.
description	Information about the Duo Windows Logon client system as reported by the application. user_agent The Duo Windows Logon application version information and the Windows OS version and platform information. hostname The host name of the system where Duo Windows Logon is installed. factor The type of authenticator used for offline access. One of “duo_otp” or “security_key”.
isotimestamp	ISO8601 timestamp of the event.
object	The Duo Windows Logon integration's name.
timestamp	Unix timestamp of the event.
username	The Duo username.

Example Response

{
  "stat": "OK",
  "response": [{
      "action": "o2fa_user_provisioned",
      "description": "{\"user_agent\": \"DuoCredProv/4.0.6.413 (Windows NT 6.3.9600; x64; Server)\", \"hostname\": \"WKSW10x64\", \"factor\": \"duo_otp\"}",
      "isotimestamp": "2019-08-30T16:10:05+00:00",
      "object": "Acme Laptop Windows Logon",
      "timestamp": 1567181405,
      "username": "narroway"
  }]
}

Trust Monitor

Retrieve Events

Returns a paged list of events surfaced by Trust Monitor from the last 180 days. To fetch all results, call repeatedly with the next_offset paging parameter as long as the result metadata has next_offset values. Requires "Grant read log" API permission.

We recommend requesting Trust Monitor events no more than once per minute.

GET /admin/v1/trust_monitor/events

Paging Parameter	Required?	Description
limit	Optional	The maximum number of records returned. Default: 100; Max: 500
offset	Optional	The offset from 0 at which to start record retrieval. When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: 0

Query Parameters

Query Parameter	Required?	Description
mintime	Required	Return records that have a 13 character Unix timestamp in milliseconds of mintime or later. This value must be strictly less then maxtime.
maxtime	Required	Return records that have a 13 character Unix timestamp in milliseconds of maxtime or earlier. This value must be strictly greater then mintime.
type	Optional	The type of security event. Type Description auth Return security events that are denied anomalous authentications. bypass_status_enabled Return security events that are bypass status enabled.

Response Codes

Response	Meaning
200	Success. Returns a list of security events.
400	Invalid or missing parameters.

Response Format

Key

Value

events

Array of events that match the query parameters. The information returned for each event includes: bypass_status_enabled Unix timestamp in milliseconds when bypass status was enabled for the user or group. Returned for events with type=bypass_status. enabled_by The application or the administrator that enabled bypass status. Returned for events with type=bypass_status. enabled_for The user or group with bypass status. Returned for events with type=bypass_status. explanations An array of objects describing why Trust Monitor surfaced the event. Returned for events with type=auth. from_common_netblock A boolean describing if this event was created from a common IP netblock. Returned for events with type=auth. from_new_user A boolean describing if this event was created for a new user. Returned for events with type=auth. low_risk_ip A boolean describing if this event was created from an IP address identified in the Risk Profile configuration as a low risk IP address. Returned for events with type=auth. priority_event A boolean describing if the event matches the Risk Profile configuration. priority_reasons An object describing how the event matches the Trust Monitor Risk Profile configuration. Returned for events with type=auth. sekey The unique identifier for this event as a 20 character string. This is unique across all different event types. state A string describing the state of the event. One of statenew or stateprocessed. state_updated_timestamp Unix timestamp in milliseconds of the last change to the state of the event. surfaced_auth An object which represents the actual authentication. See the Authentication Logs response format for authentication event details. Returned for events with type=auth. surfaced_timestamp Unix timestamp in milliseconds when the event was surfaced by Trust Monitor. triaged_as_interesting A boolean describing if this event was triaged as being interesting or not interesting. triage_event_uri A string representing the URI of the security event, which a Duo administrator can use to view and process the surfaced event in the Duo Admin Panel. Returned for events with type=auth. type The type of event, as a string. One of auth or bypass_status.

Example Response

Authentication Event:

{
    "response": {
        "events": [
                        {
                "explanations": [
                    {
                        "summary": "amanda_tucker has not logged in from this location recently.",
                        "type": "NEW_COUNTRY_CODE"
                    },
                    {
                        "summary": "amanda_tucker has not logged in from this IP recently.",
                        "type": "NEW_NETBLOCK"
                    },
                    {
                        "summary": "amanda_tucker has not accessed this application recently.",
                        "type": "NEW_IKEY"
                    }
                ],
                "from_common_netblock": true,
                "from_new_user": false,
                "low_risk_ip": false,
                "priority_event": true,
                "priority_reasons": [
                    {
                        "label": "CN",
                        "type": "country"
                    }
                ],
                "sekey": "SEDOR9BP00L23C6YUH5",
                "state": "new",
                "state_updated_timestamp": null,
                "surfaced_auth": {
                    "access_device": {
                        "browser": "Chrome",
                        "browser_version": "86.0.4240.198",
                        "flash_version": null,
                        "hostname": null,
                        "ip": "17.88.232.83",
                        "is_encryption_enabled": "unknown",
                        "is_firewall_enabled": "unknown",
                        "is_password_set": "unknown",
                        "java_version": null,
                        "location": {
                            "city": "Shanghai",
                            "country": "China",
                            "state": "Shanghai"
                        },
                        "os": "Windows",
                        "os_version": "10",
                        "security_agents": "unknown"
                    },
                    "alias": "unknown",
                    "application": {
                        "key": "DIUD2X62LHMPDP00LXS3",
                        "name": "Microsoft Azure Active Directory"
                    },
                    "auth_device": {
                        "ip": null,
                        "location": {
                            "city": null,
                            "country": null,
                            "state": null
                        },
                        "name": null
                    },
                    "email": "",
                    "event_type": null,
                    "factor": "not_available",
                    "isotimestamp": "2020-11-17T03:19:13.092+00:00",
                    "ood_software": "",
                    "reason": "location_restricted",
                    "result": "denied",
                    "timestamp": 1605583153,
                    "trusted_endpoint_status": null,
                    "txid": "436694ad-467c-4aed-b048-8ad--f58e04c",
                    "user": {
                        "groups": [
                            "crazy"
                        ],
                        "key": "DUN73JE5M92DP00L4ZYS",
                        "name": "amanda_tucker"
                    }
                },
                "surfaced_timestamp": 1605602911680,
                "triage_event_uri": "https://admin-xxxxxxxx.duosecurity.com/trust-monitor?sekey=SEDOR9BP00L23C6YUH5",
                "triaged_as_interesting": false,
                "type": "auth"
            }
        ],
        "metadata": {
            "next_offset": "31229"
        }
    },
    "stat": "OK"
}

Bypass Status Enabled Event:

{
    "response": {
        "events": [
                        {
                "bypass_status_enabled": 1604337058989,
                "enabled_by": {
                    "key": "DEWGH6P00LT2R0I60UI",
                    "name": "Ellery Munson"
                },
                "enabled_for": {
                    "key": "DUN73JE5M92DP00L4ZYS",
                    "name": "amanda_tucker"
                },
                "priority_event": true,
                "priority_reasons": [],
                "sekey": "SEDOR9BP00L23C6YUH5",
                "state": "new",
                "state_updated_timestamp": null,
                "surfaced_timestamp": 1605602911680,
                "triaged_as_interesting": false,
                "type": "bypass_status"
            }
        ],
        "metadata": {}
    },
    "stat": "OK"
}

Settings

Retrieve Settings

Returns global Duo settings. These settings can also be viewed and set in the Admin Panel. Requires "Grant settings" API permission.

GET /admin/v1/settings

Parameters

None.

Response Codes

Response	Meaning
200	Success. Returns settings.

Response Format

Key	Value
caller_id	Automated calls will appear to come from this number. This does not apply to text messages.
fraud_email	The email address to be notified when a user reports a fraudulent authentication attempt or is locked out due to failed authentication attempts. All administrators will be notified if this is not set.
fraud_email_enabled	If true, emailed notifications of user-reported fraudulent authentication attempts and user lockouts due to failed authentication are sent to the email address defined for fraud_email, or to all administrators if fraud_email is not defined. If set to false, no fraud alert emails are sent.
inactive_user_expiration	Users will be automatically deleted if they are inactive (no successful logins) for a this amount of days.
keypress_confirm	The key for users to press to authenticate, or empty if any key should be pressed to authenticate.
keypress_fraud	The key for users to press to report fraud, or empty if any key should be pressed to authenticate.
language	The language used in the browser-based user authentication prompt. One of: “EN”, “DE”, “FR”. Default: “EN”
lockout_expire_duration	If non-zero, the time in minutes until a locked-out user’s status reverts to “Active”. If “null” or “0”, a user remains locked out until their status is manually changed (By an admin or API call). Minimum: 5 minutes. Maximum: 30000 minutes.
lockout_threshold	The number of consecutive failed authentication attempts before the user’s status is set to “Locked Out” and the user is denied access.
minimum_password_length	The minimum number of characters that an administrator’s Duo Admin Panel password must contain. This is only enforced on password creation and reset; existing passwords will not be invalidated. Default: 12.
mobile_otp_enabled	If true, users will be able to use authenticate with a passcode generated by Duo Mobile. If false, users will not be able to authenticate with a passcode generated by Duo Mobile. Note that if false, this will override Duo Mobile passcodes for any groups.
name	The customer name.
password_requires_lower_alpha	If true, administrator passwords will be required to contain a lower case alphabetic character. If false, administrator passwords will not be required to contain a lower case alphabetic character. This is only enforced on password creation and reset; existing passwords will not be invalidated. Default: false.
password_requires_numeric	If true, administrator passwords will be required to contain a numeric character. If false, administrator passwords will not be required to contain a numeric character. This is only enforced on password creation and reset; existing passwords will not be invalidated. Default: false.
password_requires_special	If true, administrator passwords will be required to contain a special (non-alphanumeric) character. If false, administrator passwords will not be required to contain a special (non-alphanumeric) character. This is only enforced on password creation and reset; existing passwords will not be invalidated. Default: false.
password_requires_upper_alpha	If true, administrator passwords will be required to contain an upper case alphabetic character. If false, administrator passwords will not be required to contain an upper case alphabetic character. This is only enforced on password creation and reset; existing passwords will not be invalidated. Default: false.
push_enabled	If true, users will be able to use Duo Push to authenticate. If false, users will not be able to use Duo Push to authenticate. Note that if false, this will override push_enabled for any groups.
sms_batch	How many passcodes to send at one time, up to 10.
sms_enabled	If true, users will be able to use SMS passcodes to authenticate. If false, users will not be able to use SMS passcodes to authenticate. Note that if false, this will override sms_enabled for any groups.
sms_expiration	The time in minutes to expire and invalidate SMS passcodes.
sms_message	Description sent with every batch of SMS passcodes.
sms_refresh	If “1”, a new set of SMS passcodes will automatically be sent after the last one is used. If “0”, a new set will not be sent.
telephony_warning_min	This is the number of telephony credits at which an alert will be sent for low credits.
timezone	This is the timezone used when displaying timestamps in the administrative interface.
voice_enabled	If true, users will be able to use authenticate with voice callback. If false, users will not be able to authenticate with voice callback. Note that if false, this will override voice_enabled for any groups.
user_telephony_cost_max	The maximum number of telephony credits a user may consume in a single authentication event. This excludes Duo administrators authenticating to the Duo administration panel. Default: 20.
u2f_enabled	If true, users will be able to use authenticate with a U2F device. If false, users will not be able to authenticate with a U2F device. Default: false.

Example Response

{
  "stat": "OK",
  "response": {
      "caller_id": "+15035551000",
      "fraud_email": "example@example.com",
      "fraud_email_enabled": true,
      "helpdesk_bypass": "allow",
      "helpdesk_bypass_expiration": 0,
      "inactive_user_expiration": 30,
      "keypress_confirm": "#",
      "keypress_fraud": "*",
      "language": "EN",
      "lockout_expire_duration": null,
      "lockout_threshold": 10,
      "log_retention_days": null,
      "minimum_password_length": 12,
      "mobile_otp_enabled": true,
      "name": "Acme Corp",
      "password_requires_lower_alpha": true,
      "password_requires_numeric": true,
      "password_requires_special": false,
      "password_requires_upper_alpha": true,
      "push_enabled": true,
      "req_fips_passcodes_android": false,
      "security_checkup_enabled": 1,
      "sms_batch": 1,
      "sms_enabled": true,
      "sms_expiration": 10,
      "sms_message": "SMS passcodes",
      "sms_refresh": 0,
      "telephony_warning_min": 0,
      "timezone": "UTC",
      "user_telephony_cost_max": 20.0,
      "voice_enabled": true,
  }
}

Modify Settings

Change global Duo settings. Requires "Grant settings" API permission.

POST /admin/v1/settings

Parameters

Parameter	Required?	Description
caller_id	Optional	Automated calls will appear to come from this number. This does not apply to text messages.
fraud_email	Optional	The email address to be notified when a user reports a fraudulent authentication attempt or is locked out due to failed authentication attempts, or empty for all administrators will be notified. If fraud_email is set to a specific email address and fraud_email_enabled is set to false, the specific email address value is cleared.
fraud_email_enabled	Optional	Set to true to enable fraudulent authentication notification emails. False disables the fraud email functionality. If fraud_email is set to a specific email address and fraud_email_enabled is set to false, the specific email address value is cleared.
inactive_user_expiration	Optional	Users will be automatically deleted if they are inactive (no successful logins) for a this amount of days. Minimum: 30 days. Maximum: 365 days.
keypress_confirm	Optional	The key for users to press to authenticate, or empty if any key should be pressed to authenticate. If this is empty, keypress_fraud must be as well.
keypress_fraud	Optional	The key for users to report fraud, or empty if any key should be pressed to authenticate. If this is empty, keypress_confirm must be as well.
language	Optional	Sets the language used in the browser-based user authentication prompt. One of: “EN”, “DE”, “FR”. Default: “EN”
lockout_expire_duration	Optional	If non-zero, the time in minutes until a locked-out user’s status reverts to “Active”. If 0, a user remains locked out until their status is manually changed (By an admin or API call). Minimum: 5 minutes. Maximum: 30000 minutes.
lockout_threshold	Optional	The number of consecutive failed authentication attempts before the user’s status is set to “Locked Out” and the user is denied access.
minimum_password_length	Optional	The minimum number of characters that an administrator’s Duo Admin Panel password must contain. This is only enforced on password creation and reset; existing passwords will not be invalidated. Default: 12.
mobile_otp_enabled	Optional	If true, users will be able to use authenticate with a passcode generated by Duo Mobile. If false, users will not be able to authenticate with a passcode generated by Duo Mobile. Note that if false, this will override Duo Mobile passcodes for any groups.
password_requires_lower_alpha	Optional	If true, administrator passwords will be required to contain a lower case alphabetic character. If false, administrator passwords will not be required to contain a lower case alphabetic character. This is only enforced on password creation and reset; existing passwords will not be invalidated. Default: false.
password_requires_numeric	Optional	If true, administrator passwords will be required to contain a numeric character. If false, administrator passwords will not be required to contain a numeric character. This is only enforced on password creation and reset; existing passwords will not be invalidated. Default: false.
password_requires_special	Optional	If true, administrator passwords will be required to contain a special (non-alphanumeric) character. If false, administrator passwords will not be required to contain a special (non-alphanumeric) character. This is only enforced on password creation and reset; existing passwords will not be invalidated. Default: false.
password_requires_upper_alpha	Optional	If true, administrator passwords will be required to contain an upper case alphabetic character. If false, administrator passwords will not be required to contain an upper case alphabetic character. This is only enforced on password creation and reset; existing passwords will not be invalidated. Default: false.
push_enabled	Optional	If true, users will be able to use Duo Push to authenticate. If false, users will not be able to use Duo Push to authenticate. Note that if false, this will override push_enabled for any groups.
sms_batch	Optional	How many passcodes to send at one time, up to 10.
sms_enabled	Optional	If true, users will be able to use SMS passcodes to authenticate. If false, users will not be able to use SMS passcodes to authenticate. Note that if false, this will override sms_enabled for any groups.
sms_expiration	Optional	The time in minutes to expire and invalidate SMS passcodes, or empty if they should not expire.
sms_message	Optional	Description sent with every batch of SMS passcodes.
sms_refresh	Optional	If 1, a new set of SMS passcodes will automatically be sent after the last one is used. If 0, a new set will not be sent.
telephony_warning_min	Optional	Configure a alert to be sent when the account has fewer than this many telephony credits remaining.
timezone	Optional	This is the timezone used when displaying timestamps in the administrative interface. Timezones must be entries in the IANA Time Zone Database, for example, “US/Eastern”, “Australia/Darwin”, “GMT”.
voice_enabled	Optional	If true, users will be able to authenticate using voice callback. If false, users will not be able to authenticate using voice callback. Note that if false, this will override voice_enabled for any groups.
user_telephony_cost_max	Optional	The maximum number of telephony credits a user may consume in a single authentication event. This excludes Duo administrators authenticating to the Duo administration panel. Default: 20.
u2f_enabled	Optional	If true, users will be able to use authenticate with a U2F device. If false, users will not be able to authenticate with a U2F device. Default: false.

Response Codes

Response	Meaning
200	The settings were modified successfully. The settings object is also returned (see Retrieve Settings).
400	Invalid or missing parameters. For example, inactive_user_expiration out of bounds.

Response Format

Same as Retrieve Settings.

Example Response

Same as Retrieve Settings.

Retrieve Duo Mobile Logo

Returns the logo to display in Duo Mobile. Requires "Grant settings API permission.

GET /admin/v1/logo

Parameters

None.

Response Codes

Response	Meaning
200	Success. Returns PNG data.
404	No logo currently configured.

Response Format

If there are no errors, a PNG image is returned instead of JSON and the Content-Type header is image/png.

Modify Duo Mobile Logo

Set or replace the logo to display in Duo Mobile. This logo is sent to devices when they enroll with the mobile app. Currently enrolled devices must be re-activated to receive the new logo. Requires "Grant settings" API permission.

POST /admin/v1/logo

Parameters

Parameter	Required?	Description
logo	Required	Base-64 encoded PNG image data. The logo image must be in PNG format and not exceed 500 by 500 pixels and 200 KB. We recommend a 304 by 304 pixel logo image with a transparent background for the best results.

Response Codes

Response	Meaning
200	Success.
400	Invalid or missing parameters or PNG data.

Response Format

Empty string.

Delete Duo Mobile Logo

Remove the logo from future activation of Duo Mobile. Currently enrolled devices must be re-activated to remove the logo. Requires "Grant settings" API permission.

DELETE /admin/v1/logo

Parameters

None.

Response Codes

Response	Meaning
200	The logo was deleted or did not exist.

Response Format

Empty string.

Account Info

Retrieve Summary

Returns a summary of account utilization information. Requires "Grant read information" API permission.

GET /admin/v1/info/summary

Parameters

None.

Response Codes

Response	Meaning
200	Success.

Response Format

Key	Value
admin_count	Current number of admins in the account.
integration_count	Current number of integrations in the account.
telephony_credits_remaining	Current total number of telephony credits available in the account. This is the sum of all types of telephony credits.
user_count	Current number of users in the account.

Example Response

{
  "stat": "OK",
  "response": {
    "admin_count": 3,
    "integration_count": 9,
    "telephony_credits_remaining": 960,
    "user_count": 8
  }
}

Telephony Credits Used Report

Retrieve the number of telephony credits used in a given time period. Requires "Grant read information" API permission.

If the specified time period is too long you may need to call this multiple times with mintime and sum the results.

GET /admin/v1/info/telephony_credits_used

Parameters

Parameter	Required?	Description
maxtime	Optional	Limit report to events before this UNIX timestamp. Defaults to the current time.
mintime	Optional	Limit report to events after this UNIX timestamp. Defaults to thirty days before maxtime.

Response Codes

Response	Meaning
200	Success.
400	Invalid or missing parameters or mintime is after the maxtime.

Response Format

Key	Value
mintime	UNIX timestamp for the beginning of the report period.
maxtime	UNIX timestamp for the end of the report period.
telephony_credits_used	Number of telephony credits spent during the specified time period.

Example Response

{
  "stat": "OK",
  "response": [{
    "maxtime": 1352880416,
    "mintime": 1350288416,
    "telephony_credits_used": 30
  }]
}

Authentication Attempts Report

Retrieve counts of authentication attempts for a given time period (not to exceed 180 days), broken down by result. Requires "Grant read information" API permission.

GET /admin/v1/info/authentication_attempts

Parameters

Parameter	Required?	Description
maxtime	Optional	Limit report to events before this UNIX timestamp. Defaults to the current time.
mintime	Optional	Limit report to events after this UNIX timestamp. Defaults to thirty days before maxtime.

Response Codes

Response	Meaning
200	Success.
400	Invalid or missing parameters, mintime is outside the 180 day retention window, or mintime is after the maxtime.

Response Format

Key	Value
mintime	UNIX timestamp for the beginning of the report period.
maxtime	UNIX timestamp for the end of the report period.
authentication_attempts	Number of authentication attempts during the specified time period, broken down by result: Result Meaning “ERROR” An unexpected failure prevented authentication (for example, an invalid telephone number). “FAILURE” Authentication was denied. “FRAUD” The attempt ended with a report of fraudulent activity. “SUCCESS” Authentication was allowed.

Example Response

{
  "stat": "OK",
  "response": [{
    "authentication_attempts": {
      "ERROR": 0,
      "FAILURE": 1,
      "FRAUD": 1,
      "SUCCESS": 50
    },
    "maxtime": 1352880416,
    "mintime": 1350288416
  }]
}

Users with Authentication Attempts Report

Retrieve counts of users with authentication attempts for a given time period (not to exceed 180 days), broken down by result. Each count is the number of users who had at least one authentication attempt ending with that result. Requires "Grant read information" API permission.

GET /admin/v1/info/user_authentication_attempts

Parameters

Parameter	Required?	Description
maxtime	Optional	Limit report to events before this UNIX timestamp. Defaults to the current time.
mintime	Optional	Limit report to events after this UNIX timestamp. Defaults to thirty days before maxtime.

Response Codes

Response	Meaning
200	Success.
400	Invalid or missing parameters, mintime is outside the 180 day retention window, or mintime is after the maxtime.

Response Format

Key	Value
mintime	UNIX timestamp for the beginning of the report period.
maxtime	UNIX timestamp for the end of the report period.
user_authentication_attempts	Number of users with authentication attempts during the specified time period, broken down by result. Refer to Authentication Attempts Report for a list of result types and their meanings.

Example Response

{
  "stat": "OK",
  "response": [{
    "maxtime": 1352880416,
    "mintime": 1350288416,
    "user_authentication_attempts": {
      "ERROR": 0,
      "FAILURE": 1,
      "FRAUD": 1,
      "SUCCESS": 10
    }
  }]
}

Troubleshooting

Need some help? Take a look at our Admin API Knowledge Base articles or Community discussions. For further assistance, contact Support.