Contents
The Duo Admin API provides programmatic access to the administrative functionality of Duo Security's two-factor authentication platform.
Overview
Duo Admin API is automatically available to paying Duo Premier, Duo Advantage, and Duo Essentials plan customers and new customers with an Advantage or Premier trial. Learn how to sign up for a Duo account and receive a free 30-day Duo Advantage trial.
The Admin API lets developers integrate with Duo Security's platform at a low level. The API has methods for creating, retrieving, updating, and deleting the core objects in Duo's system: users, phones, hardware tokens, admins, and integrations.
Developers can write applications that programmatically read their Duo account's authentication logs, administrator logs, and telephony logs; read or update account settings; and retrieve reports and other information.
Review the API Details to see how to construct your first API request.
Are you a software vendor looking to integrate Duo into your application? Join our free Duo Technology Partner Program for developer accounts, joint marketing support, and more!
About the Admin API
Documented properties will not be removed within a stable version of the API. Once a given API endpoint is documented to return a given property, a property with that name will always appear (although certain properties may only appear under certain conditions, like if the customer is using a specific edition). When Duo deprecates a property, the API continues to accept that property in requests, although it no longer has any effect.
Properties that enumerate choices may gain new values at any time, e.g. the device platform
value could return new device platforms that did not previously exist. Duo may cease to return legacy values for properties as well. Duo will update our API documentation with changes to property values in a timely fashion, adding new property values or indicating changes to existing property values.
New, undocumented properties may also appear at any time. For instance, Duo may make available a beta feature involving extra information returned by an API endpoint. Until the property is documented here its format may change or it may even be entirely removed from our API.
We have started implementing v2 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, except where noted.
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.
- Sign up for a Duo account if you aren't already a customer. Your free 30-day Duo Advantage trial includes Admin API access.
- Log in to the Duo Admin Panel and navigate to Applications.
- 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.
- Determine the permissions you want to grant to this Admin API application. Refer to the API endpoint descriptions throughout this document for information about required permissions for operations.
Permission Details Grant administrators - Read The Admin API application can read information about Duo administrators and administrative units. Grant administrators - Write The Admin API application can read, add, modify, and delete information about Duo administrators and administrative units. Grant read information The Admin API application can read information about the Duo customer account's utilization. Grant applications The Admin API application can add, modify, and delete applications (referred to as "integrations" in the API), including permissions on itself or other Admin API applications. Grant settings The Admin API application can read and change global Duo account settings. Grant read log The Admin API application can read authentication, offline access, telephony, and administrator action log information. Grant resource - Read The Admin API application can read information about resource objects such as end users and devices. Grant resource - Write The Admin API application can create, update, and delete resource objects such as end users and devices. Optionally specify which IP addresses or ranges are allowed to use this Admin API application in Networks for API Access. If you do not specify any IP addresses or ranges, this Admin API application may be accessed from any network.
The Admin API performs the IP check after verifying the authentication signature in a request. If you restrict the allowed networks for API access and see logged events for blocked Admin API requests from unrecognized IP addresses, this may indicate compromise of your Admin API application's secret key.
This application communicates with Duo's service on SSL TCP port 443.
Firewall configurations that restrict outbound access to Duo's service with rules using destination IP addresses or IP address ranges aren't recommended, since these may change over time to maintain our service's high availability. If your organization requires IP-based rules, please review Duo Knowledge Base article 1337.
Effective June 30, 2023, Duo no longer supports TLS 1.0 or 1.1 connections or insecure TLS/SSL cipher suites. See Duo Knowledge Base article 7546 for additional guidance.
API Clients
Duo Security has demonstration clients available on GitHub to call the Duo API methods.
- Python (duo_client_python)
- Java (duo_client_java)
- C# (duo_api_csharp)
- Go (duo_api_golang)
- Node (duo_api_nodejs)
- Ruby (duo_api_ruby)
- Perl (duo_api_perl)
- PHP (duo_api_php)
API Details
Base URL
All API methods use your API hostname,
https://api-XXXXXXXX.duosecurity.com
. Obtain this value from the Duo Admin Panel and use it exactly as shown there.
Methods always use HTTPS. Unsecured HTTP is not supported.
Request Format
All requests must have "Authorization" and "Date" headers.
If the request method is GET
or DELETE
, URL-encode parameters and send them in the URL query string like this: /admin/v1/users?realname=First%20Last&username=root
. They still go on a separate line when creating the string to sign for an Authorization header.
Send parameters for POST
requests in the body as URL-encoded key-value pairs (the same request format used by browsers to submit form data).
The header "Content-Type: application/x-www-form-urlencoded
" must also be present.
When URL-encoding, all bytes except ASCII letters, digits, underscore ("_"), period ("."), tilde ("~"), and hyphen ("-") are replaced by a percent sign ("%") followed by two hexadecimal digits containing the value of the byte. For example, a space is replaced with "%20" and an at-sign ("@") becomes "%40". Use only upper-case A through F for hexadecimal digits.
A request with parameters, as a complete URL, would look like this: https://api-XXXXXXXX.duosecurity.com/admin/v1/users?realname=First%20Last&username=root
.
Response Format
Responses are formatted as a JSON object with a top-level stat
key.
Successful responses will have a stat
value of "OK" and a
response
key. The response
will either
be a single object or a sequence of other JSON types, depending
on which endpoint is called.
{
"stat": "OK",
"response": {
"key": "value"
}
}
Values are returned as strings unless otherwise documented.
Unsuccessful responses will have a
stat
value of "FAIL", an integer
code
, and a
message
key that further describes the failure.
A message_detail
key may be present if additional information is available (like the specific parameter that caused the error).
{
"stat": "FAIL",
"code": 40002,
"message": "Invalid request parameters",
"message_detail": "username"
}
The HTTP response code will be the first three digits of the more
specific code
found inside the JSON object. Each
endpoint's documentation lists HTTP response codes it can return.
Additionally, all API endpoints that require a signed request can
return the following HTTP response codes:
Response | 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
|
An integer indicating the total number of objects retrieved by the API request across all pages of results. |
next_offset
|
An integer indicating The offset from If not present in the metadata response, then there are no more pages of results left. |
prev_offset
|
An integer indicating the offset from |
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 If a request specifies a value greater than the endpoint's maximum |
offset
|
Optional |
The offset from When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: |
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 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. |
An example 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 RElXSjhYNkFFWU9SNU9NQzZUUTE6YzFlZjQzNzY3YzNlYjNiMzI1OGRiZGRjYTZmOGQwOTQxZTA4NWI5Mg==
Host: api-XXXXXXXX.duosecurity.com
Content-Length: 35
Content-Type: application/x-www-form-urlencoded
Separate HTTP request header lines with CRLF newlines.
The following Python function can be used to construct the "Authorization" and "Date" headers:
import base64, email.utils, hmac, hashlib, urllib
def sign(method, host, path, params, skey, ikey):
"""
Return HTTP Basic Authentication ("Authorization" and "Date") headers.
method, host, path: strings from request
params: dict of request parameters
skey: secret key
ikey: integration key
"""
# create canonical string
now = email.utils.formatdate()
canon = [now, method.upper(), host.lower(), path]
args = []
for key in sorted(params.keys()):
val = params[key].encode("utf-8")
args.append(
'%s=%s' % (urllib.parse.
quote(key, '~'), urllib.parse.quote(val, '~')))
canon.append('&'.join(args))
canon = '\n'.join(canon)
# sign canonical string
sig = hmac.new(bytes(skey, encoding='utf-8'),
bytes(canon, encoding='utf-8'),
hashlib.sha1)
auth = '%s:%s' % (ikey, sig.hexdigest())
# return headers
return {'Date': now, 'Authorization': 'Basic %s' % base64.b64encode(bytes(auth, encoding="utf-8")).decode()}
import base64, email, hmac, hashlib, urllib
def sign(method, host, path, params, skey, ikey):
"""
Return HTTP Basic Authentication ("Authorization" and "Date") headers.
method, host, path: strings from request
params: dict of request parameters
skey: secret key
ikey: integration key
"""
# create canonical string
now = email.Utils.formatdate()
canon = [now, method.upper(), host.lower(), path]
args = []
for key in sorted(params.keys()):
val = params[key]
if isinstance(val, unicode):
val = val.encode("utf-8")
args.append(
'%s=%s' % (urllib.quote(key, '~'), urllib.quote(val, '~')))
canon.append('&'.join(args))
canon = '\n'.join(canon)
# sign canonical string
sig = hmac.new(skey, canon, hashlib.sha1)
auth = '%s:%s' % (ikey, sig.hexdigest())
# return headers
return {'Date': now, 'Authorization': 'Basic %s' % base64.b64encode(auth)}
If you receive 401 error responses to your API requests, check the following:
- Is the
Authorization
header correctly formatted? If not, you may receive a 40101 error. - Does your framework override the
Date
header? The HTTPDate:
header must be exactly the same string as was signed. This could result in a 40103 error. - Are the
Date
and time zone used RFC 3339 compliant?? If not, you may get a 40104 or 40105 response. - Are the parameters lexicographically sorted?
- Did you include a line for parameters when constructing the signature, even if you're not passing in any parameters?
- Are any hex digits lower-case?
- Are the
Content-Length
andContent-Type
parameters correct? If not, your parameters may be ignored or you may receive a 40103 response because your signature considered parameters that the service didn't receive.
Users
Retrieve Users
Returns a paged list of users. To fetch all results, call repeatedly with the offset
parameter as long as the result metadata has a next_offset
value. If username
is not provided, the list will contain all users. If username
is provided, the list will either contain a single user (if a match was found) or no users. Requires "Grant resource - Read" API permission.
GET /admin/v1/users
Parameters
Use the paging parameters to change the number of results shown in a response or to retrieve additional results. See Response Paging for details.
Paging Parameter | Required? | Description |
---|---|---|
limit
|
Optional |
The maximum number of records returned. Default: |
offset
|
Optional |
The offset from When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: |
usernames
|
Deprecated |
Retrieve specific users by specifying up to 100 List format:
Ignores other paging parameters when used. |
user_ids
|
Deprecated |
Retrieve specific users by specifying up to 100 List format:
Ignores other paging parameters when used. |
user_id_list
|
Optional |
A list of user ids used to fetch multiple users by If you provide this parameter, you must not provide the Must be a JSON serialized array. |
username_list
|
Optional |
A list of usernames used to fetch multiple users by If you provide this parameter, you must not provide the Must be a JSON serialized array. |
Parameter | Required? | Description |
---|---|---|
username
|
Optional | Specify a user name (or username alias) to look up a single user. |
email
|
Optional | Specify an email address 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
|
Map of the user's username alias(es). Up to eight aliases may exist. |
||||||||||||
created
|
The user's creation date as a Unix timestamp. |
||||||||||||
email
|
The user's email address. |
||||||||||||
enable_auto_prompt
|
If |
||||||||||||
external_id
|
The user's unique identifier imported by a directory sync. This is the |
||||||||||||
firstname
|
Legacy parameter; returns no value. The user's given name. |
||||||||||||
groups
|
List of groups to which this user belongs. See Retrieve Groups for response info. |
||||||||||||
is_enrolled
|
Is |
||||||||||||
last_directory_sync
|
An integer indicating the last update to the user via directory sync as a Unix timestamp, or |
||||||||||||
last_login
|
An integer indicating the last time this user logged in, as a Unix timestamp, or |
||||||||||||
lastname
|
Legacy parameter; returns no value. The user's surname. |
||||||||||||
lockout_reason
|
The user's lockout_reason. One of:
| ||||||||||||
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:
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. U2F tokens were deprecated in Duo in February 2022.
|
||||||||||||
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",
"enable_auto_prompt": true,
"external_id": "1a2345b6-7cd8-9e0f-g1hi-23j45kl6m789",
"firstname": "",
"groups": [
{
"desc": "People with hardware tokens",
"group_id": "DGBDKSSH37KSJ373JKSU",
"mobile_otp_enabled": false,
"name": "token_users",
"push_enabled": false,
"sms_enabled": false,
"status": "Active",
"voice_enabled": false
}
],
"is_enrolled": true,
"last_directory_sync": 1508789163,
"last_login": 1343921403,
"lastname": "",
"lockout_reason": null,
"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": "123456",
"token_id": "DHIZ34ALBA2445ND4AI2",
"type": "d1"
}
],
"u2ftokens": [],
"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"
}
],
},
{
"alias1": "chris.jones",
"alias2": "cjones@example.com",
"alias3": null,
"alias4": null,
"aliases": {
"alias1": "chris.jones",
"alias2": "cjones@example.com"
},
"created": 1489612829,
"email": "cjones@example.com",
"enable_auto_prompt": false,
"firstname": "",
"groups": [],
"is_enrolled": true,
"last_directory_sync": null,
"last_login": 1343821403,
"lastname": "",
"notes": "",
"phones": [
{
"activated": true,
"capabilities": [
"auto",
"push",
"sms",
"phone",
"mobile_otp"
],
"encrypted": "Encrypted",
"extension": "",
"fingerprint": "Configured",
"last_seen": "2019-11-19T15:51:13",
"model": "Google Pixel 3",
"name": "Pixel3",
"number": "15555550200",
"phone_id": "DPFZRS9FB0D46QFTP00L",
"platform": "Google Android",
"postdelay": "0",
"predelay": "0",
"screenlock": "Locked",
"sms_passcodes_sent": false,
"tampered": "Not tampered",
"type": "Mobile"
}
],
"realname": "Chris Jones",
"status": "active",
"tokens": [],
"u2ftokens": [],
"user_id": "DU3RP9I2WOC59VZXJ05H",
"username": "cjones",
"webauthncredentials": [
{
"credential_name": "YubiKey",
"date_added": 1550564764,
"label": "yubikey",
"webauthnkey": "WA4BD9AUVMSNUFWZJ05H"
}
]
}
]
}
Create User
Create a new user with the specified username
. Requires "Grant resource - Write" API permission.
POST /admin/v1/users
Parameters
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
|
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. |
||||||||
realname
|
Optional |
The real name (or full name) of this user. |
||||||||
email
|
Optional |
The email address of this user. |
||||||||
enable_auto_prompt
|
Optional |
If set to |
||||||||
status
|
Optional |
The user's status. One of:
|
||||||||
notes
|
Optional |
An optional description or notes field. Can be viewed in the Duo Admin Panel. |
||||||||
firstname
|
Optional |
Legacy parameter; no effect if specified. The user's given name. |
||||||||
lastname
|
Optional |
Legacy parameter; no effect if specified. 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 new single user object. Refer to Retrieve Users for an explanation of the object's keys.
Example Response
{
"stat": "OK",
"response":{
"alias1": null,
"alias2": null,
"alias3": null,
"alias4": null,
"aliases": {},
"created": 1657222760,
"email": "jperez@example.com",
"enable_auto_prompt": true,
"firstname": "",
"groups": [],
"is_enrolled": false,
"last_directory_sync": null,
"last_login": null,
"lastname": "",
"lockout_reason": null,
"notes": "",
"phones": [],
"realname": "Juan Perez",
"status": "active",
"tokens": [],
"u2ftokens": [],
"user_id": "DU0W79YFWZAJWJV6P00L",
"username": "jperez",
"webauthncredentials": []
}
}
Create Multiple Users
Create multiple users at once. If one user fails to add, the entire operation fails. You can create a maximum of 100 users per request at a rate limit of 50 calls per minute. Requires "Grant resource - Write" API permission.
POST /admin/v1/users/bulk_create
Parameters
Parameter | Required? | Description |
---|---|---|
users
|
Yes |
Must be a serialized JSON list of objects, each of which contains information for a new user. For more information, see the list of user object attributes. |
User Object Attributes
Parameter | Required? | Description | ||||||||
---|---|---|---|---|---|---|---|---|---|---|
username
|
Yes |
Username of the user to create. |
realname
|
No |
The real name (or full name) of this user. |
|||||
email
|
No |
The email address of this user. |
||||||||
status
|
No |
The user's status. One of:
|
||||||||
notes
|
No |
An optional description or notes field. Can be viewed in the Duo Admin Panel. |
||||||||
firstname
|
No |
Legacy parameter; no effect if specified. The user's given name. |
||||||||
lastname
|
No |
Legacy parameter; no effect if specified. The user's surname. |
Response Format
Returns a list of response objects, one for each operation provided. The response format for each operation will follow the same format as that of the corresponding single-operation endpoint for that operation. For example, a Create User operation will receive a response in the format described in Create User.
Note that it is possible for some operations to fail while others succeed. The list of responses can include both successful responses as well as unsuccessful responses due to invalid parameters or rate limiting.
Response Codes
Response | Meaning |
---|---|
200 | Success. Returns the list of newly created users. |
400 |
Invalid or missing parameters, or user already exists for the given username provided.
|
429 | Rate limited. |
Example Request
Here’s a sample python script that uses the admin api client to call out to the new endpoint. Note that the “users” param is a JSON serialized string.
{
#!/usr/bin/python
from __future__ import absolute_import
from __future__ import print_function
import pprint
import sys
import json
import duo_client
from six.moves import input
# Configuration and information about objects to create.
admin_api = duo_client.Admin(
ikey='DIWJ8X6AEYOR5OMC6TQ1',
skey='Zh5eGmUq9zpfQnyUIu5OL9iWoMMv5ZNmk3zLJ4Ep',
host='api-XXXXXXXX.duosecurity.com',
ca_certs='DISABLE'
)
response = admin_api.json_api_call(
'POST',
'/admin/v1/users/bulk_create',
{
'users': json.dumps([
{
'username': 'example_username_1',
'email': 'example_user_1@example.com'
},
{
'username': 'example_username_2',
'status': 'disabled'
}
])
}
)
pprint.pprint(response)
}
Example Response
Here’s the output from running the above script. Note that the shape of the user objects returned here is consistent with the shape returned from other Admin API user operations (e.g. creating a single user). The returned users will be in the same order that they were received.
{
"[{'alias1': None,
'alias2': None,
'alias3': None,
'alias4': None,
'aliases': {},
'created': 1677770740,
'email': 'example_user_1@example.com',
'firstname': None,
'groups': [],
'is_enrolled': False,
'last_directory_sync': None,
'last_login': None,
'lastname': None,
'lockout_reason': "null",
'notes': '',
'phones': [],
'realname': '',
'status': 'active',
'tokens': [],
'u2ftokens': [],
'user_id': 'DUVI0UT8SKB5P70WG42Z',
'username': 'example_username_1',
'webauthncredentials': []},
{'alias1': None,
'alias2': None,
'alias3': None,
'alias4': None,
'aliases': {},
'created': 1677770740,
'email': '',
'firstname': None,
'groups': [],
'is_enrolled': False,
'last_directory_sync': None,
'last_login': None,
'lastname': None,
'notes': '',
'phones': [],
'realname': '',
'status': 'disabled',
'tokens': [],
'u2ftokens': [],
'user_id': 'DU2X1VOO31O10F2ZNF43',
'username': 'example_username_2',
'webauthncredentials': []}]
}
}
Retrieve User by ID
Return the single user with user_id
. Requires "Grant resource - Read" API permission.
GET /admin/v1/users/[user_id]
Parameters
This API endpoint has no parameters.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
404 |
No user was found with the given user_id .
|
Response Format
Returns a single user object. Refer to Retrieve Users for an explanation of the object's keys.
Example Response
{
"stat": "OK",
"response": {
"alias1": "joe.smith",
"alias2": "jsmith@example.com",
"alias3": null,
"alias4": null,
"aliases": {
"alias1": "joe.smith",
"alias2": "jsmith@example.com"
},
"created": 1489612729,
"email": "jsmith@example.com",
"enable_auto_prompt": true,
"external_id": "1a2345b6-7cd8-9e0f-g1hi-23j45kl6m789",
"firstname": "",
"groups": [
{
"desc": "People with hardware tokens",
"group_id": "DGBDKSSH37KSJ373JKSU",
"mobile_otp_enabled": false,
"name": "token_users",
"push_enabled": false,
"sms_enabled": false,
"status": "Active",
"voice_enabled": false
}
],
"is_enrolled": true,
"last_directory_sync": 1508789163,
"last_login": 1343921403,
"lastname": "",
"lockout_reason": null,
"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": "123456",
"token_id": "DHIZ34ALBA2445ND4AI2",
"type": "d1"
}
],
"u2ftokens": [],
"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"
}
],
}
}
Modify User
Change the username, username aliases, full name, status, and/or notes section of the user with ID user_id
. Requires "Grant resource - Write" API permission.
POST /admin/v1/users/[user_id]
Parameters
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
|
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. |
realname
|
Optional |
The new real name (or full name). |
email
|
Optional |
The new email address. |
enable_auto_prompt
|
Optional |
If set to |
status
|
Optional |
The new status. Must be one of "active", "disabled", or "bypass", or "locked out". See Retrieve Users for an explanation of these fields. The "disabled" status may not be set via Admin API for users managed by Active Directory or Entra ID sync, nor can the API set "active" status for users disabled by directory sync. |
notes
|
Optional |
The new notes field. |
firstname
|
Optional |
Legacy parameter; no effect if specified. The user's new given name. |
lastname
|
Optional |
Legacy parameter; no effect if specified. 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 |
Response Format
Returns the modified single user object. Refer to Retrieve Users for an explanation of the object's keys.
Example Response
Same as Retrieve User by ID.
Delete User
Delete the user with ID user_id
from the system. The API will not delete phones associated only with that user right away; remove them immediately with Delete Phone. This method returns 200 if the phone was found or if no such phone exists. Requires "Grant resource - Write" API permission.
Users deleted by the API do not get moved into the Trash view as "Pending Deletion" as they would if removed by directory sync, user deletion, or interactively from the Duo Admin Panel, and therefore are not available for restoration. Users deleted via the API are immediately and permanently removed from Duo.
DELETE /admin/v1/users/[user_id]
Parameters
This API endpoint has no parameters.
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 resource - Write" 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 remain valid.
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. To preserve existing bypass codes instead of clearing them the request must specify preserve_existing=true
.
Requires "Grant resource - Write" API permission.
Object limits: 100 bypass codes per user.
POST /admin/v1/users/[user_id]/bypass_codes
Parameters
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. |
preserve_existing
|
Optional |
Preserves existing bypass codes while creating new ones. Either If true and the request would result the target user reaching the limit of 100 codes per user, or if |
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 for which generated bypass codes remain valid. 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 resource - Read" API permission.
GET /admin/v1/users/[user_id]/bypass_codes
Parameters
Use the paging parameters to change the number of results shown in a response or to retrieve additional results. See Response Paging for details.
Paging Parameter | Required? | Description |
---|---|---|
limit
|
Optional |
The maximum number of records returned. Default: |
offset
|
Optional |
The offset from When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: |
This API endpoint has no additional parameters.
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
|
An integer indicating the expiration timestamp of the bypass code, or null if the bypass code does not expire on a certain date.
|
reuse_count
|
An integer indicating 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": [
{
"admin_email": "janesmith@example.com",
"bypass_code_id": "DB2A9F0012RL54001FA3",
"created": 1522260759,
"expiration": 1522264359,
"reuse_count": 1
}
]
}
Retrieve Groups by User ID
Returns a paged list of groups associated with the user with ID user_id
. To fetch all results, call repeatedly with the offset
parameter as long as the result metadata has a next_offset
value. Requires "Grant resource - Read" API permission.
GET /admin/v1/users/[user_id]/groups
Parameters
Use the paging parameters to change the number of results shown in a response or to retrieve additional results. See Response Paging for details.
Paging Parameter | Required? | Description |
---|---|---|
limit
|
Optional |
The maximum number of records returned. Default: |
offset
|
Optional |
The offset from When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: |
This API endpoint has no additional parameters.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
404 |
No user was found with the given user_id .
|
Response Format
Returns the groups for the user object. Refer to Retrieve Groups for an explanation of the object keys.
Example Response
{
"stat": "OK",
"response": [
{
"desc": "This is group A",
"group_id": "DGBDKSSH37KSJ373JKSU",
"mobile_otp_enabled": false
,
"name": "Group A",
"push_enabled": false,
"sms_enabled": false,
"status": "active",
"voice_enabled": false
},
{
"desc": "This is group B",
"group_id": "DGJKSLSH393YSJD93HSD3",
"mobile_otp_enabled": false,
"name": "Group B (from Microsoft Entra ID sync \"Acme Corp Entra ID\")",
"push_enabled": false,
"sms_enabled": false,
"status": "active",
"voice_enabled": false
}
]
}
Associate Group with User
Associate a group with ID group_id
with the user with ID user_id
. Requires "Grant resource - Write" API permission.
Object limits: 100 groups per user.
POST /admin/v1/users/[user_id]/groups
Parameters
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 resource - Write" API permission.
DELETE /admin/v1/users/[user_id]/groups/[group_id]
Parameters
This API endpoint has no parameters.
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 resource - Read" API permission.
GET /admin/v1/users/[user_id]/phones
Parameters
Use the paging parameters to change the number of results shown in a response or to retrieve additional results. See Response Paging for details.
Paging Parameter | Required? | Description |
---|---|---|
limit
|
Optional |
The maximum number of records returned. Default: |
offset
|
Optional |
The offset from When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: |
This API endpoint has no additional parameters.
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 resource - Write" 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 resource - Write" API permission.
DELETE /admin/v1/users/[user_id]/phones/[phone_id]
Parameters
This API endpoint has no parameters.
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 resource - Read" API permission.
GET /admin/v1/users/[user_id]/tokens
Parameters
Use the paging parameters to change the number of results shown in a response or to retrieve additional results. See Response Paging for details.
Paging Parameter | Required? | Description |
---|---|---|
limit
|
Optional |
The maximum number of records returned. Default: |
offset
|
Optional |
The offset from When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: |
This API endpoint has no additional parameters.
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 admins
or users
attribute.
Example Response
{
"stat": "OK",
"response": [
{
"serial": "123456",
"token_id": "DHEKH0JJIYC1LX3AZWO4",
"totp_step": null,
"type": "d1"
},
{
"serial": "123457",
"token_id": "DHUNT3ZVS3ACF8AEV2WG",
"totp_step": null,
"type": "d1"
}
]
}
Associate Hardware Token with User
Associate a hardware token with the user with ID user_id
. Requires "Grant resource - Write" API permission.
Object limits: 100 tokens per user.
POST /admin/v1/users/[user_id]/tokens
Parameters
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 resource - Write" API permission.
DELETE /admin/v1/users/[user_id]/tokens/[token_id]
Parameters
This API endpoint has no parameters.
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
The U2F Tokens by User ID API endpoint /admin/v1/users/[user_id]/u2ftokens
is deprecated as of February 2022. This API no longer allows listing all U2F tokens for a user. Requests to this endpoint now fail with the following response:
{
"stat": "FAIL",
"code": 40301,
"message": "Access forbidden",
}
Retrieve WebAuthn Credentials by User ID
Returns a list of WebAuthn credentials associated with the user with ID user_id
. Requires "Grant resource - Read" API permission.
GET /admin/v1/users/[user_id]/webauthncredentials
Parameters
This API endpoint has no parameters.
Response Codes
Response | 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. Example: Windows Hello or iCloud Keychain .
|
webauthnkey
|
The WebAuthn credential's registration identifier. |
Example Response
{
"stat": "OK",
"response": [
{
"credential_name": "YubiKey 5",
"date_added": 1550674764,
"label": "Security Key",
"webauthnkey": "WA4ED9AUVMSWUF00KES4"
}
],
}
Retrieve Desktop Authenticators by User ID
Returns a paged list of desktop authenticators associated with the user with ID user_id
. To fetch all results, call repeatedly with the offset
parameter as long as the result metadata has a next_offset
value. Requires "Grant resource - Read" API permission.
GET /admin/v1/users/[user_id]/desktopauthenticators
Parameters
Paging Parameter | Required? | Description |
---|---|---|
limit |
Optional |
The maximum number of records returned. Default: |
offset |
Optional |
The offset from When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: |
This API endpoint has no additional parameters.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
404 | No user was found with the given user_id . |
Response Format
Key | Value |
---|---|
daid |
The authenticator's ID. |
dakey |
The authenticator's Duo-specific identifier. |
device_name |
The endpoint's hostname. |
duo_desktop_version |
The version of Duo Desktop installed on the endpoint. |
os_family |
The endpoint's operating system platform. |
Example Response
{
"response": [
{
"daid": 365,
"dakey": "DDABCDE1FGHIJ23KL45",
"device_name": "DESKTOP-ABC1234",
"duo_desktop_version": "6.12.0",
"os_family": "Windows"
}
],
"stat": "OK"
}
Synchronize User from Directory
Initiate a sync to create, update, or mark for deletion the user specified by username
against the directory specified by the directory_key
. The directory_key
for a directory can be found by navigating to Users → Directory Sync in the Duo Admin Panel, and then clicking on the configured directory. Learn more about syncing individual users from Active Directory, OpenLDAP, or Entra ID. Requires "Grant resource - Write" API permission.
POST /admin/v1/users/directorysync/[directory_key]/syncuser
Parameters
Parameter | Required? | Description |
---|---|---|
username
|
Required | The user to update or create via directory sync. This should be the same as the value for the user's username attribute in the source directory as configured in the sync. |
Response Codes
Response | Meaning |
---|---|
200 | The user was synced successfully and updated or added in Duo. The user object is also returned (see Retrieve Users). |
404 |
The specified username or directory_key was incorrect, the user is not managed by the specified directory, or the user is not a member of any source directory group specified in the sync configuration.
|
429 | Too many requests; try again later. |
Response Format
Returns the single synced user object with an additional message
stating the user synced successfully. Refer to Retrieve Users for an explanation of the object's keys.
Example Response
{
"stat": "OK",
"response":{
"message": "User wwu synced successfully.",
"user": {
"alias1": "wwu@example.com",
"alias2": null,
"alias3": null,
"alias4": null,
"aliases": {
"alias1": "wwu@example.com"
},
"created": 1553271753,
"email": "",
"enable_auto_prompt": true,
"external_id": "1a2345b6-7cd8-9e0f-g1hi-23j45kl6m789",
"firstname": "",
"groups": [
{
"desc": "",
"group_id": "DGKAT4WCV306FOONUNIC",
"mobile_otp_enabled": false,
"name": "Duo Users (from AD sync \"Acme Sync")",
"push_enabled": false,
"sms_enabled": false,
"status": "Active",
"voice_enabled": false
}
],
"is_enrolled": true,
"last_directory_sync": 1657227493,
"last_login": 1553271773,
"lastname": "",
"lockout_reason": null,
"notes": "",
"phones": [],
"realname": "Wang Wu",
"status": "active",
"tokens": [],
"u2ftokens": [],
"user_id": "DUYGKDZI47WEJIIXU6QI",
"username": "wwu",
"webauthncredentials": [
{
"credential_name": "YubiKey",
"date_added": 1553271760,
"label": "Security Key",
"webauthnkey": "WAYRDI633R1219HM1BN7"
}
]
}
}
}
Send Verification Push
Sends a verification Duo Push to the user with ID user_id
. Verification pushes can also be sent from the Duo Admin Panel. Requires "Grant resource - Write" API permission.
POST /admin/v1/users/[user_id]/send_verification_push
Parameters
Parameter | Required? | Description |
---|---|---|
phone_id |
Required | The ID of the phone belonging to the user. This phone should be activated for push. |
Response Codes
Response | Meaning |
---|---|
200 | Success. |
400 | Invalid parameters or phone cannot receive pushes. |
404 | No user was found with the given user_id or no phone was found with the given phone_id . |
Response Format
Key | Value |
---|---|
confirmation_code |
The Duo Push sent to the user contains this confirmation code. |
push_id |
The ID of the Duo Push sent. |
Example Response
{
"response": {
"confirmation_code": "123456",
"push_id": "123abc45-6def-789g-h012-34567ijk8901"
},
"stat": "OK"
}
Retrieve Verification Push Response
Retrieves the verification push result for the user with ID user_id
. Push response information will be available for 120 seconds after the push was sent, after which this endpoint will return a 404. If no success or failure response was returned by this endpoint during these 120 seconds, it can be assumed that the push has timed out. Requires "Grant resource - Read" API permission.
GET /admin/v1/users/[user_id]/verification_push_response
Parameters
Parameter | Required? | Description |
---|---|---|
push_id |
Required | The ID of the Duo Push sent. |
Response Codes
Response | Meaning |
---|---|
200 | Success. |
404 |
Invalid or expired push_id . Note that the push_id expires after 120 seconds.
|
Response Format
Key | Value | push_id |
The ID of the Duo Push sent. |
---|---|
result |
The result of the verification push sent. One of:
|
Example Response
{
"response": {
"push_id": "123abc45-6def-789g-h012-34567ijk8901"
"result": "approve"
},
"stat": "OK"
}
Bulk Operations
Bulk User Operations
Performs a list of operations serially in the order provided. You can perform a maximum of 50 operations per request at a rate limit of 50 calls per minute. Requires "Grant resource - Write" API permission.
POST /admin/v1/bulk
Parameters
Parameter | Required? | Description |
---|---|---|
operations
|
Yes | Must be a JSON list of objects, each of which specifies an operation. |
Operations
Each operation must be a JSON object that specifies the following attributes.
Parameter | Required? | Description |
---|---|---|
method
|
Yes |
HTTP method “POST” or “DELETE”. |
path
|
Yes |
HTTP path for the operation. See below for a list of enabled operations. |
body
|
Yes |
A JSON object containing the parameters for this operation. |
Valid Operations
Operation | Method | Path | Body |
---|---|---|---|
Create User |
POST
|
/admin/v1/users
|
See Parameters section from Create User. |
Modify User |
POST
|
/admin/v1/users/[user_id]
|
See Parameters section from Modify User. |
Delete User |
DELETE
|
/admin/v1/users/[user_id]
|
See Parameters section from Delete User. |
Associate Group with User |
POST
|
/admin/v1/users/[user_id]/groups
|
See Parameters section from Associate Group with User. |
Disassociate Group from User |
POST
|
/admin/v1/users/[user_id]/groups/[group_id]
|
See Parameters section from Disassociate Group from User. |
Response Codes
Response | Meaning |
---|---|
200 | Success. |
400 |
Invalid request, possibly due to the shape of the operations attribute being invalid.
|
429 | Too many requests. |
Response Format
Returns a list of response objects, one for each operation provided. The response format for each operation will follow the same format as that of the corresponding single-operation endpoint for that operation. For example, a Create User operation will receive a response in the format described in Create User.
Note that it is possible for some operations to fail while others succeed. The list of responses can include both successful responses as well as unsuccessful responses due to invalid parameters or rate limiting.
Example Operations list
This sample list of operations provides an example of what should be passed as the operations
parameter.
{
[
{
"method": "POST",
"path": "/admin/v1/users",
"body": {
"username": "uname1",
"alias1": "my_alias1",
"alias2": "my_alias2",
"alias3": "my_alias3",
"alias4": "my_alias4",
"email": "user@example.com",
"status": "active",
"notes": "This is a user"
}
},
{
"method": "POST",
"path": "/admin/v1/users/DUJ424R8DJFJ05HASDFJ",
"body": {
"username": "uname2",
"alias2": "updated_alias2",
"email": "user2@example.com",
"status": "active",
"notes": "This is another user"
}
},
{
"method": "DELETE",
"path": "/admin/v1/users/DUJ424R8DJFJ05HASDFJ",
"body": {}
},
{
"method": "POST",
"path": "/admin/v1/users/DUJ424R8DJFJ05HASDFJ/groups",
"body": {
"group_id": "DGBDKSSH37KSJ373JKSU",
}
},
{
"method": "DELETE",
"path": "/admin/v1/users/DUJ424R8DJFJ05HASDFJ/groups/DGBDKSSH37KSJ373JKSU",
"body": {}
}
]
}
Example Response
{
[
{
"stat": "OK",
"response":{
"alias1": "my_alias1",
"alias2": "my_alias2",
"alias3": "my_alias3",
"alias4": "my_alias4",
"aliases": {
"alias1": "my_alias1",
"alias2": "my_alias2",
"alias3": "my_alias3",
"alias4": "my_alias4",
},
"created": 1657222760,
"email": "user@example.com",
"enable_auto_prompt": true,
"firstname": "",
"groups": [],
"is_enrolled": false,
"last_directory_sync": null,
"last_login": null,
"lastname": "",
"lockout_reason": null,
"notes": "This is a user",
"phones": [],
"realname": "",
"status": "active",
"tokens": [],
"u2ftokens": [],
"user_id": "DUJ424R8DJFJ05HASDFJ",
"username": "uname1",
"webauthncredentials": []
}
},
{
"stat": "OK",
"response":{
"alias1": null,
"alias2": "my_alias2",
"alias3": null,
"alias4": null,
"aliases": {
"alias2": "updated_alias2",
},
"created": 1657223860,
"email": "user2@example.com",
"enable_auto_prompt": true,
"firstname": "",
"groups": [],
"is_enrolled": false,
"last_directory_sync": null,
"last_login": null,
"lastname": "",
"lockout_reason": null,
"notes": "This is another user",
"phones": [],
"realname": "",
"status": "active",
"tokens": [],
"u2ftokens": [],
"user_id": "DUJ424R8DP0OL5D4DAFJ",
"username": "uname2",
"webauthncredentials": []
}
},
{
"stat": "OK",
"response": ""
},
{
"stat": "OK",
"response": ""
},
{
"stat": "OK",
"response": ""
}
]
}
Groups
Per-user Group Operations
See Retrieve Groups by User ID, Associate Group with User, and Disassociate Group from User.
Retrieve Groups
Returns a paged list of groups. To fetch all results, call repeatedly with the offset
parameter as long as the result metadata has a next_offset
value. Requires "Grant resource - Read" API permission.
GET /admin/v1/groups
Parameters
Use the paging parameters to change the number of results shown in a response or to retrieve additional results. See Response Paging for details.
Paging Parameter | Required? | Description |
---|---|---|
limit
|
Optional |
The maximum number of records returned. Default: |
offset
|
Optional |
The offset from When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: |
group_ids
|
Deprecated |
Retrieve specific groups by specifying up to 200 List format:
Ignores other paging parameters when used. |
group_id_list
|
Optional |
A list of group ids used to fetch multiple groups by If you provide this parameter, the Must be a JSON serialized array. |
This API endpoint has no additional parameters.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
Response Format
Key | Value | ||||||||
---|---|---|---|---|---|---|---|---|---|
desc
|
The group's description. | ||||||||
group_id
|
The group's ID. | ||||||||
mobile_otp_enabled
|
Legacy parameter; no effect if specified and always returns |
||||||||
name
|
The group's name. If managed by directory sync, then the name returned here also indicates the source directory. | ||||||||
push_enabled
|
Legacy parameter; no effect if specified and always returns |
||||||||
sms_enabled
|
Legacy parameter; no effect if specified and always returns |
||||||||
status
|
The group's authentication status. May be one of:
|
||||||||
voice_enabled
|
Legacy parameter; no effect if specified and always returns |
Example Response
{
"stat": "OK",
"response": [
{
"desc": "This is group A",
"group_id": "DGBDKSSH37KSJ373JKSU",
"mobile_otp_enabled": false
,
"name": "Group A",
"push_enabled": false,
"sms_enabled": false,
"status": "Active",
"voice_enabled": false
},
{
"desc": "This is group B",
"group_id": "DGJKSLSH393YSJD93HSD3",
"mobile_otp_enabled": false,
"name": "Group B (from Microsoft Entra ID sync \"Acme Corp Entra ID\")",
"push_enabled": false,
"sms_enabled": false,
"status": "Active",
"voice_enabled": false
}
],
}
Create Group
Create a new group. Requires "Grant resource - Write" API permission.
POST /admin/v1/groups
Parameters
Parameter | Required? | Description |
---|---|---|
name
|
Required | The name of the group. |
desc
|
Optional | The description of the group. |
push_enabled
|
Optional |
Legacy parameter; no effect if specified and always returns |
sms_enabled
|
Optional |
Legacy parameter; no effect if specified and always returns |
voice_enabled
|
Optional |
Legacy parameter; no effect if specified and always returns |
mobile_otp_enabled
|
Optional |
Legacy parameter; no effect if specified and always returns |
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
|
Legacy parameter; no effect if specified and always returns |
sms_enabled
|
Legacy parameter; no effect if specified and always returns |
voice_enabled
|
Legacy parameter; no effect if specified and always returns |
mobile_otp_enabled
|
Legacy parameter; no effect if specified and always returns |
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
{
"stat": "OK",
"response": {
"desc": "This is an example group",
"group_id": "DGBDKSSH37KSJ373JKSU",
"mobile_otp_enabled": false,
"name": "Example Group",
"push_enabled": false,
"sms_enabled": false,
"status": "active",
"voice_enabled": false
}
}
Get Group Info
Retrieve information about a group. Note that this output does not include a list of group members. To retrieve group members, use /admin/v2/groups/[group_id]/users
. Requires "Grant resource - Read" API permission.
GET /admin/v2/groups/[group_id]
Parameters
This API endpoint has no parameters.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
404 | Group with given ID was not found. |
Response Format
Key | Value |
---|---|
desc
|
The group's description. |
push_enabled
|
Legacy parameter; no effect if specified and always returns |
sms_enabled
|
Legacy parameter; no effect if specified and always returns |
voice_enabled
|
Legacy parameter; no effect if specified and always returns |
mobile_otp_enabled
|
Legacy parameter; no effect if specified and always returns |
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
{
"stat": "OK",
"response": {
"desc": "Group description",
"group_id": "DGBDKSSH37KSJ373JKSU",
"mobile_otp_enabled": false,
"name": "Group Name",
"push_enabled": false,
"sms_enabled": false,
"status": "active",
"voice_enabled": false
}
}
Returns a paged list of members of a specified group. To fetch all results, call repeatedly with the offset
parameter as long as the result metadata has a next_offset
value.
GET /admin/v2/groups/[group_id]/users
Parameters
Use the paging parameters to change the number of results shown in a response or to retrieve additional results. See Response Paging for details.
Paging Parameter | Required? | Description |
---|---|---|
limit
|
Optional |
The maximum number of records returned. Default: |
offset
|
Optional |
The offset from When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: |
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
{
"stat": "OK",
"metadata": {
"total_objects": 4
},
"response": [
{
"user_id": "DUJF3424R8DJFJ05HASD",
"username": "user1"
},
{
"user_id": "DUJSFP005D4DJFJ05HSD",
"username": "user2"
},
{
"user_id": "DUJSFP001D4DJFJB0OFS",
"username": "user3"
}
]
}
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 resource - Read" API permission.
GET /admin/v1/groups/[group_id]
Parameters
This API endpoint has no parameters.
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
|
Legacy parameter; no effect if specified and always returns |
sms_enabled
|
Legacy parameter; no effect if specified and always returns |
voice_enabled
|
Legacy parameter; no effect if specified and always returns |
mobile_otp_enabled
|
Legacy parameter; no effect if specified and always returns |
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
{
"stat": "OK",
"response": {
"desc": "Group description",
"group_id": "DGBDKSSH37KSJ373JKSU",
"mobile_otp_enabled": false,
"name": "Group Name",
"push_enabled": false,
"sms_enabled": false,
"status": "active",
"users": [
{
"user_id": "DUJ424R8DP0OL5D4DAFJ",
"username": "User A"
},
{
"user_id": "DUJSP005D4DJFJ05HASD",
"username": "User B"
}
],
"voice_enabled": false
}
}
Update Group
Update information about a group. Requires "Grant resource - Write" 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 |
Legacy parameter; no effect if specified and always returns |
sms_enabled | Optional |
Legacy parameter; no effect if specified and always returns |
voice_enabled | Optional |
Legacy parameter; no effect if specified and always returns |
mobile_otp_enabled | Optional |
Legacy parameter; no effect if specified and always returns |
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
|
Legacy parameter; no effect if specified and always returns |
sms_enabled
|
Legacy parameter; no effect if specified and always returns |
voice_enabled
|
Legacy parameter; no effect if specified and always returns |
mobile_otp_enabled
|
Legacy parameter; no effect if specified and always returns |
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
{
"stat": "OK",
"response": {
"desc": "Group description",
"group_id": "DGBDKSSH37KSJ373JKSU",
"mobile_otp_enabled": false,
"name": "Group Name",
"push_enabled": false,
"sms_enabled": false,
"status": "active",
"voice_enabled": false
}
}
Delete Group
Delete a group. Requires "Grant resource - Write" API permission.
DELETE /admin/v1/groups/[group_id]
Parameters
This API endpoint has no parameters.
Response Codes
Response | Meaning |
---|---|
200 | The group was deleted or did not exist. |
Response Format
Empty string.
Example Response
{
"response": "",
"stat": "OK"
}
Phones
Per-user Phone Operations
See Retrieve Phones by User ID, Associate Phone with User, and Disassociate Phone from User.
Retrieve Phones
Returns a paged list of phones. To fetch all results, call repeatedly with the offset
parameter as long as the result metadata has a next_offset
value. If no number
or extension
parameters are provided, the list will contain all phones. Otherwise, the list will contain either single phone (if a match was found), or no phones. Requires "Grant resource - Read" API permission.
GET /admin/v1/phones
Parameters
Use the paging parameters to change the number of results shown in a response or to retrieve additional results. See Response Paging for details.
Paging Parameter | Required? | Description |
---|---|---|
limit
|
Optional |
The maximum number of records returned. Default: |
offset
|
Optional |
The offset from When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: |
Parameter | Required? | Description |
---|---|---|
number
|
Optional | Specify a phone number in E.164 format 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 |
||||||||||||
capabilities
|
List of strings, each a factor that can be used with the device.
|
||||||||||||
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 Premier and Duo Advantage 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 Premier and Duo Advantage plan customers. |
||||||||||||
last_seen
|
An integer indicating 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 in E.164 format. 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 Premier and Duo Advantage plan customers. |
||||||||||||
sms_passcodes_sent
|
Have SMS passcodes been sent to this phone? Either |
||||||||||||
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 Premier and Duo Advantage plan customers. |
||||||||||||
type
|
The type of phone. One of: "unknown", "mobile", or "landline". |
||||||||||||
users
|
A list of users associated with this phone. See Retrieve Users for descriptions of the response fields. |
Example Response
{
"stat": "OK",
"response": [
{
"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": "",
"predelay": "",
"screenlock": "Locked",
"sms_passcodes_sent": false,
"tampered": "Not tampered",
"type": "Mobile",
"users": [
{
"alias1": "joe.smith",
"alias2": "jsmith@example.com"
"alias3": null,
"alias4": null,
"aliases": {
"alias1": "joe.smith",
"alias2": "jsmith@example.com"
},
"created": 1509717442,
"email": "jsmith@example.com",
"enable_auto_prompt": true,
"firstname": "",
"is_enrolled": false,
"last_directory_sync": null,
"last_login": 1474399627,
"lastname": "",
"notes": "",
"realname": "Joe Smith",
"status": "active",
"user_id": "DUJZ2U4L80HT45MQ4EOQ",
"username": "jsmith"
}
]
},
{
"activated": true,
"capabilities": [
"auto",
"push",
"sms",
"phone",
"mobile_otp"
],
"encrypted": "Encrypted",
"extension": "",
"fingerprint": "Configured",
"last_seen": "2019-11-19T15:51:13",
"model": "Google Pixel 3",
"name": "Pixel3",
"number": "15555550200",
"phone_id": "DPFZRS9FB0D46QFTP00L",
"platform": "Google Android",
"postdelay": "0",
"predelay": "0",
"screenlock": "Locked",
"sms_passcodes_sent": false,
"tampered": "Not tampered",
"type": "Mobile"
"users": [
{
"alias1": "chris.jones",
"alias2": "cjones@example.com",
"alias3": null,
"alias4": null,
"aliases": {
"alias1": "chris.jones",
"alias2": "cjones@example.com"
},
"created": 1489612829,
"email": "cjones@example.com",
"enable_auto_prompt": true,
"firstname": "",
"groups": [],
"is_enrolled": true,
"last_directory_sync": null,
"last_login": 1343821403,
"lastname": "",
"notes": "",
"realname": "Chris Jones",
"status": "active",
"user_id": "DU3RP9I2WOC59VZXJ05H",
"username": "cjones"
}
]
}
]
}
Create Phone
Create a new phone with a specified phone number or other parameters. Requires "Grant resource - Write" API permission.
POST /admin/v1/phones
Parameters
Parameter | Required? | Description |
---|---|---|
number
|
Optional |
The phone number; E.164 format recommended (i.e. "+17345551212"). If no leading plus sign is provided then it is assumed to be a United States number and an implicit "+1" country code is prepended. Dashes and spaces are ignored. 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
Returns the single phone object created. Refer to Retrieve Phones for an explanation of the object's keys.
Example Response
{
"stat": "OK",
"response":{
"activated": false,
"capabilities": [],
"extension": "",
"last_seen": "",
"model": "Unknown",
"name": "",
"number": "15555551111",
"phone_id": "DP1D9EZJNZNQXJ05HKJB",
"platform": "Generic Smartphone",
"postdelay": "",
"predelay": "",
"sms_passcodes_sent": false,
"type": "Unknown",
"users": []
}
}
Retrieve Phone by ID
Return the single phone with phone_id
. Requires "Grant resource - Read" API permission.
GET /admin/v1/phones/[phone_id]
Parameters
This API endpoint has no parameters.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
404 |
No phone was found with the given phone_id .
|
Response Format
Returns a single phone object. Refer to Retrieve Phones for an explanation of the object's keys.
Example Response
{
"stat": "OK",
"response": {
"activated": true,
"capabilities": [
"auto",
"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",
"enable_auto_prompt": true,
"firstname": "",
"is_enrolled": false,
"last_directory_sync": null,
"last_login": 1474399627,
"lastname": "",
"notes": "",
"realname": "Joe Smith",
"status": "active",
"user_id": "DUJZ2U4L80HT45MQ4EOQ",
"username": "jsmith",
}
]
}
}
Modify Phone
Change the details of the phone with ID phone_id
. Requires "Grant resource - Write" API permission.
POST /admin/v1/phones/[phone_id]
Parameters
Parameter | Required? | Description |
---|---|---|
number
|
Optional |
The new phone number; E.164 format recommended (i.e. "+17345551212"). If no leading plus sign is provided then it is assumed to be a United States number and an implicit "+1" country code is prepended. Dashes and spaces are ignored. |
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
Returns the modified single phone object. Refer to Retrieve Phones for an explanation of the object's keys.
Example Response
Same as Retrieve Phone by ID.
Delete Phone
Delete the phone with ID phone_id
from the system. Requires "Grant resource - Write" API permission.
DELETE /admin/v1/phones/[phone_id]
Parameters
This API endpoint has no parameters.
Response Codes
Response | 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 resource - Write" API permission.
POST /admin/v1/phones/[phone_id]/activation_url
Parameters
Parameter | Required? | Description |
---|---|---|
valid_secs
|
Optional |
The number of seconds this activation code remains valid. Default: 86400 (one day). Expiration not supported for legacy phone platforms that support passcode generation only (not Duo Push).
|
install
|
Optional |
Specify 1 to also return an installation URL for Duo Mobile; 0 to not return a URL.
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_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 .
|
activation_url
|
Opening this URL on a phone with the Duo Mobile app installed will automatically complete activation. |
installation_url
|
Opening this URL on the phone will prompt the user to install Duo Mobile. Only present if install was 1 .
|
valid_secs
|
An integer indicating the number of seconds that the activation code remains valid. |
Example Response
{
"stat": "OK",
"response": {
"activation_barcode": "https://api-abcdefgh.duosecurity.com/frame/qr?value=duo%3A%2F%2Factivation-code",
"activation_url": "https://m-abcdefgh.duosecurity.com/iphone/7dmi4Oowz5g3J47FARLs",
"valid_secs": 3600
}
}
Send Activation Code via SMS
Generate a Duo Mobile activation code and send it to the phone via SMS, optionally sending an additional message with a URL to install Duo Mobile. This method will fail if the phone's type or platform are Unknown. Requires "Grant resource - Write" API permission.
SMS Size Limits
The recommended maximum length for activation_msg
and installation_msg
is 80 characters.
Activation and installation SMS messages are limited to 160 characters or less. If providing custom text, please make sure to leave enough room for a URL to be sent in the same message. The exact length available for custom text varies depending on the device's platform and whether international characters were used. Activation URLs are typically about 60 characters long. Installation URLs are between 50 and 75 characters long.
POST /admin/v1/phones/[phone_id]/send_sms_activation
Parameters
Parameter | Required? | Description |
---|---|---|
valid_secs
|
Optional |
The number of seconds this activation code remains valid. Default: 86400 (one day).
|
install
|
Optional |
Specify 1 to cause an installation SMS message to be sent before the activation message, or 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
|
An integer indicating the number of seconds that the activation URL remains valid. |
Example Response
{
"stat": "OK",
"response": {
"activation_barcode": "https://api-abcdef/frame/qr\?*value=duo%3A%2F%2FXoudqt8a9F-Jqt",
"activation_msg": "To activate the Duo Mobile app, click this link: https://m-eval.duosecurity.com/iphone/7dmi4Oowz5g3J47FARLs",
"installation_msg": "Welcome to Duo! To install the Duo Mobile app, click this link: http://m-eval.duosecurity.com",
"valid_secs": 3600
}
}
Send Installation URL via SMS
Send a message via SMS describing how to install Duo Mobile. This method will fail if the phone's type or platform are Unknown. Requires "Grant resource - Write" API permission.
SMS Size Limits
The recommended maximum length for installation_msg
is 80 characters.
Installation SMS messages are limited to 160 characters or less. If providing custom text, please make sure to leave enough room for a URL to be sent in the same message. The exact length available for custom text varies depending on the device's platform and whether international characters were used. Installation URLs are between 50 and 75 characters long.
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 resource - Write" API permission.
POST /admin/v1/phones/[phone_id]/send_sms_passcodes
Parameters
This API endpoint has no parameters.
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 resource - Read" API permission.
GET /admin/v1/tokens
Parameters
Use the paging parameters to change the number of results shown in a response or to retrieve additional results. See Response Paging for details.
Paging Parameter | Required? | Description |
---|---|---|
limit
|
Optional |
The maximum number of records returned. Default: |
offset
|
Optional |
The offset from When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: |
Parameter | Required? | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
type
|
Optional* |
Specify a type and serial number to look up a single hardware token. One of:
* This option is required if |
||||||||||
serial
|
Optional* |
The serial number of the hardware token. * This option is required if |
Response Codes
Response | Meaning |
---|---|
200 | Success. Returns a list of tokens. |
400 | Invalid parameters. |
Response Format
Key | Value |
---|---|
admins
|
A list of administrators associated with this hardware token. See Retrieve Administrators for descriptions of the response fields. |
serial
|
The serial number of the hardware token; used to uniquely identify
the hardware token when paired with type .
|
token_id
|
The hardware token's unique ID. |
totp_step
|
Value is null for all supported token types.
|
type
|
The type of hardware token. |
users
|
A list of end users associated with this hardware token. See Retrieve Users for descriptions of the response fields. |
Example Response
{
"stat": "OK",
"response": [
{
"admins": [
{
"admin_id": "DESMP00LIAKRJPD4DZSH",
"created": 1648143942,
"email": "jsmith@example.com",
"last_login": 1343921403,
"name": "Joe Smith"
}
],
"serial": "123456",
"token_id": "DHIZ34ALBA2445ND4AI2",
"totp_step": null,
"type": "d1",
"users": [
{
"alias1": "joe.smith",
"alias2": "jsmith@example.com",
"alias3": null,
"alias4": null,
"aliases": {
"alias1": "joe.smith",
"alias2": "jsmith@example.com"
},
"created": 1343621411,
"email": "jsmith@example.com",
"enable_auto_prompt": true,
"firstname": "",
"is_enrolled": true,
"last_directory_sync": null,
"last_login": 1343921403,
"lastname": "",
"notes": "",
"realname": "Joe Smith",
"status": "active",
"user_id": "DUJZ2U4L80HT45MQ4EOQ",
"username": "jsmith"
}
]
}
]
}
Create Hardware Token
Create a new hardware token. Requires "Grant resource - Write" API permission.
POST /admin/v1/tokens
Parameters
Parameter | Required? | Description | ||||||||
---|---|---|---|---|---|---|---|---|---|---|
type
|
Required |
The type of hardware token to import. One of:
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. This parameter is only valid for HOTP-6 and HOTP-8 hardware tokens.
Default: 0 .
|
||||||||
private_id
|
Optional | The 12-character hexadecimal YubiKey private ID. This parameter is required for YubiKey hardware tokens. | ||||||||
aes_key
|
Optional | The 32-character hexadecimal 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
Returns the created single token object. Refer to Retrieve Hardware Tokens for an explanation of the object's keys.
Example Response
{
"stat": "OK",
"response": {
"admins": [],
"serial": "123456",
"token_id": "DH6G5OP9NU4C5UP00LMN",
"totp_step": null,
"type": "h6",
"users": []
}
}
Retrieve Hardware Token by ID
Return the single hardware token with token_id
. Requires "Grant resource - Read" or "Grant resource - Write" API permission.
GET /admin/v1/tokens/[token_id]
Parameters
This API endpoint has no parameters.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
404 |
No hardware token was found with the given token_id .
|
Response Format
Returns a single user object. Refer to Retrieve Hardware Tokens for an explanation of the object's keys.
Example Response
{
"stat": "OK",
"response": {
"admins": [
{
"admin_id": "DESMP00LIAKRJPD4DZSH",
"created": 1648143942,
"email": "jsmith@example.com",
"last_login": 1343921403,
"name": "Joe Smith"
}
],
"serial": "123456",
"token_id": "DHIZ34ALBA2445ND4AI2",
"totp_step": null,
"type": "d1",
"users": [
{
"alias1": "joe.smith",
"alias2": "jsmith@example.com",
"alias3": null,
"alias4": null,
"aliases": {
"alias1": "joe.smith",
"alias2": "jsmith@example.com"
},
"created": 1343621411,
"email": "jsmith@example.com",
"enable_auto_prompt": true,
"firstname": "",
"is_enrolled": true,
"last_directory_sync": null,
"last_login": 1343921403,
"lastname": "",
"notes": "",
"realname": "Joe Smith",
"status": "active",
"user_id": "DUJZ2U4L80HT45MQ4EOQ",
"username": "jsmith"
}
]
}
}
Resync Hardware Token
Resynchronize the hardware token with ID token_id
by providing three successive codes from the token. Only HOTP and Duo-D100 tokens can be resynchronized. YubiKey tokens operating in their native AES mode do not need resynchronization. Requires "Grant resource - Write" API permission.
POST /admin/v1/tokens/[token_id]/resync
Parameters
Parameter | Required? | Description |
---|---|---|
code1
|
Required | The first code from the token. |
code2
|
Required | The second code from the token. |
code3
|
Required | The third 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 resource - Write" API permission.
DELETE /admin/v1/tokens/[token_id]
Parameters
This API endpoint has no parameters.
Response Codes
Response | Meaning |
---|---|
200 | The token was deleted or did not exist. |
Response Format
Empty string.
Example Response
{
"stat": "OK",
"response": ""
}
U2F Tokens
The U2F Tokens API endpoint /admin/v1/u2ftokens
is deprecated as of February 2022. This API no longer allows listing all U2F tokens or deletion of U2F tokens. Requests to this endpoint now fail with the following response:
{
"stat": "FAIL",
"code": 40301,
"message": "Access forbidden",
}
Per-user U2F Token Operations
See Retrieve U2F Tokens by User ID.
WebAuthn Credentials
Per-user WebAuthn Credential Operations
See Retrieve WebAuthn Credentials by User ID.
Retrieve WebAuthn Credentials
Returns a paged list of all registered WebAuthn credentials. To fetch all results, call repeatedly with the offset
parameter as long as the result metadata has a next_offset
value. Requires "Grant resource - Read" API permission to retrieve user credentials, and "Grant administrators - Read" or "Grant administrators - Write" API permission to retrieve administrator credentials.
GET /admin/v1/webauthncredentials
Parameters
Use the paging parameters to change the number of results shown in a response or to retrieve additional results. See Response Paging for details.
Paging Parameter | Required? | Description |
---|---|---|
limit
|
Optional |
The maximum number of records returned. Default: |
offset
|
Optional |
The offset from When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: |
This API endpoint has no additional parameters.
Response Codes
Response | Meaning |
---|---|
200 | Success. Returns a list of WebAuthn credentials. |
Response Format
Key | Value | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
aaguid |
A unique identifier that conveys the authenticator's make and model, or the passkey's provider identity. This value cannot be verified as accurate by Duo. | ||||||||||||
admin |
Selected information about the administrator attached to this WebAuthn credential. Returns
|
||||||||||||
backup_eligible |
If true , this credential can be used from multiple devices. If false , this credential can only be used on one device. |
||||||||||||
backup_status |
If true , this credential has been backed up and can be used from multiple devices. If false , this credential has not been backed up. |
||||||||||||
credential_id |
An identifier randomly generated by the authenticator for this WebAuthn credential. | ||||||||||||
credential_name |
Free-form label for this WebAuthn credential. | ||||||||||||
date_added |
The Unix timestamp of when this WebAuthn credential was registered in Duo. | ||||||||||||
date_last_used |
The Unix timestamp of when this WebAuthn credential was last used to authenticate with Duo. If null , this credential has not been used yet. |
||||||||||||
label |
A derived nickname for this WebAuthn credential. This value cannot be changed by a user or admin. Present when attached to a user. Example: Windows Hello or iCloud Keychain . |
||||||||||||
passwordless_authorized |
If true , this credential can be used for both MFA and Passwordless authentication. If false , this credential can only be used for MFA authentication. |
||||||||||||
registered_as |
The registration flow that was used to register this WebAuthn credential. One of platform , cross-platform , or unknown . |
||||||||||||
transports |
An array of values the browser will use to try and communicate with an authenticator during a Duo authentication attempt. | ||||||||||||
user |
Selected information about the end user attached to this WebAuthn credential. See Retrieve Users for descriptions of the response fields. |
||||||||||||
uv_capable |
If true , the authenticator is capable of locally verifying the user’s identity. If false , the authenticator cannot perform user verification. |
||||||||||||
webauthnkey |
The credential's Duo-specific identifier. |
Example Response
{
"stat": "OK",
"response": [
{
"aaguid": "abcdefgh-123i-4jkl-5mno-6p789012q3rs",
"admin": null,
"backup_eligible": true,
"backup_status": true,
"credential_id": "A1bCd34efgH5I6jK6lmnoPQrS78",
"credential_name": "Touch ID",
"date_added": 1707422111,
"label": "iCloud Keychain",
"passwordless_authorized": true,
"registered_as": "platform",
"transports": ["hybrid", "internal"],
"user": {
"alias1": joesmith,
"alias2": null,
"alias3": null,
"alias4": null,
"aliases": {},
"created": 1677007225,
"email": "",
"enable_auto_prompt": true,
"firstname": "",
"is_enrolled": true,
"last_directory_sync": null,
"last_login": 1677007248,
"lastname": "",
"notes": "",
"realname": "",
"status": "active",
"user_id": "DUDKPMBF009AHLHNDPDY",
"username": "jsmith"
},
"uv_capable": true,
"webauthnkey": "WAVTE9JYG4VSQU9LT1B4"
},
{
"aaguid": "abcdefgh-123i-4jkl-5mno-6p789012q3rs",
"admin": {
"admin_id": "DEBMWJ05HTBZBU6LNCF3",
"created": null,
"email": "ellery.munson@example.com",
"last_login": 1679420096,
"name": "Ellery Munson"
},
"backup_eligible": false,
"backup_status": false,
"credential_id": "A1bCd3_Yx7Xy8Oj_uxJKODn3WFPH7Ml4wqqLIKj5ro",
"credential_name": "Security key",
"date_added": 1679413709,
"date_last_used": 1706714235,
"label": "Security key",
"passwordless_authorized": false,
"registered_as": "unknown",
"transports": ["usb"],
"user": null,
"uv_capable": false,
"webauthnkey": "WARRM3HNRDFF3L3AQLXW"
},
]
}
Retrieve WebAuthn Credentials by Key
Return the single WebAuthn credential with webauthnkey
. Requires "Grant resource - Read" API permission to retrieve a user's credential, and "Grant administrators - Read" or "Grant administrators - Write" API permission to retrieve an administrator's credential.
GET /admin/v1/webauthncredentials/[webauthnkey]
Parameters
This API endpoint has no parameters.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
404 |
No WebAuthn credential was found with the given webauthnkey or insufficient API permission to retrieve a credential attached to an administrator.
|
Response Format
Returns a single WebAuthn credential object. Refer to Retrieve WebAuthn Credentials for an explanation of the object's keys.
Example Response
{
"stat": "OK",
"response": {
"aaguid": "abcdefgh-123i-4jkl-5mno-6p789012q3rs",
"admin": null,
"backup_eligible": true,
"backup_status": true,
"credential_id": "A1bCd34efgH5I6jK6lmnoPQrS78",
"credential_name": "Touch ID",
"date_added": 1707422111,
"label": "iCloud Keychain",
"passwordless_authorized": true,
"registered_as": "platform",
"transports": ["hybrid", "internal"],
"user": {
"alias1": joesmith,
"alias2": null,
"alias3": null,
"alias4": null,
"aliases": {},
"created": 1677007225,
"email": "",
"enable_auto_prompt": true,
"firstname": "",
"is_enrolled": true,
"last_directory_sync": null,
"last_login": 1677007248,
"lastname": "",
"notes": "",
"realname": "",
"status": "active",
"user_id": "DUDKPMBF009AHLHNDPDY",
"username": "jsmith"
},
"uv_capable": true,
"webauthnkey": "WAVTE9JYG4VSQU9LT1B4"
}
}
Delete WebAuthn Credential
Delete the WebAuthn credential with key webauthnkey
from the system. Requires "Grant resource - Write" API permission to delete a credential from a user, and "Grant administrators - Write" API permission to delete a credential from an administrator.
DELETE /admin/v1/webauthncredentials/[webauthnkey]
Parameters
This API endpoint has no parameters.
Response Codes
Response | Meaning |
---|---|
200 |
The WebAuthn credential with key webauthnkey was deleted.
|
404 |
No WebAuthn credential was found with the given webauthnkey or insufficient API permission to retrieve a credential attached to an administrator.
|
Response Format
Empty string.
Example Response
{
"stat": "OK",
"response": ""
}
Desktop Authenticators
Per-user Desktop Authenticators Operations
See Retrieve Desktop Authenticators by User ID.
Retrieve Desktop Authenticators
Returns a paged list of desktop authenticators. To fetch all results, call repeatedly with the offset
parameter as long as the result metadata has a next_offset
. Requires "Grant resource - Read" API permission.
GET /admin/v1/desktop_authenticators
Parameters
Use the paging parameters to change the number of results shown in a response or to retrieve additional results. See Response Paging for details.
Paging Parameter | Required? | Description |
---|---|---|
limit |
Optional |
The maximum number of records returned. Default: |
offset |
Optional |
The offset from When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: |
This API endpoint has no additional parameters.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
Response Format
Key | Value |
---|---|
daid |
The authenticator's ID. |
dakey |
The authenticator's Duo-specific identifier. |
device_name |
The endpoint's hostname. |
duo_desktop_version |
The version of Duo Desktop installed on the endpoint. |
os_family |
The endpoint's operating system platform. |
user |
Selected information about the end user attached to this Desktop Authenticator. See Retrieve User for descriptions of the response fields. |
Example Response
{
"response": [
{
"daid": 123,
"dakey": "DDABCDE1FGHIJ23KL4M",
"device_name": "RSANCHEZ-M-A12B",
"duo_desktop_version": "6.12.0.0",
"os_family": "Mac OS X",
"user": {
"alias1": null,
"alias2": null,
"alias3": null,
"alias4": null,
"aliases": {},
"created": 1721156264,
"email": "",
"enable_auto_prompt": true,
"firstname": "",
"is_enrolled": true,
"last_directory_sync": null,
"last_login": 1721245422,
"lastname": "",
"notes": "",
"realname": "",
"status": "active",
"user_id": "DABCDEFGHIJKL1MNOPQR",
"username": "rsanchez"
}
},
{
"daid": 234,
"dakey": "DDABCDE1FGHIJ23KL45",
"device_name": "DESKTOP-ABC1234",
"duo_desktop_version": "6.12.0",
"os_family": "Windows",
"user": {
"alias1": null,
"alias2": null,
"alias3": null,
"alias4": null,
"aliases": {},
"created": 1721156264,
"email": "",
"enable_auto_prompt": true,
"firstname": "",
"is_enrolled": true,
"last_directory_sync": null,
"last_login": 1721245422,
"lastname": "",
"notes": "",
"realname": "",
"status": "active",
"user_id": "DABCDEFGHIJKL2MNOPQR",
"username": "avandalay"
}
}
],
"stat": "OK"
}
Retrieve Desktop Authenticator by Key
Return the single desktop authenticator with dakey
. Requires "Grant resource - Read" API permission.
GET /admin/v1/desktop_authenticators/[dakey]
Parameters
This API endpoint has no parameters.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
404 | No desktop authenticator was found with the given dakey . |
Response Format
Returns a single desktop authenticator object. Refer to Retrieve Desktop Authenticators for an explanation of the object's keys.
Example Response
{
"response": {
"daid": 123,
"dakey": "DDABCDE1FGHIJ23KL4M",
"device_name": "RSANCHEZ-M-A12B",
"duo_desktop_version": "6.12.0.0",
"os_family": "Mac OS X",
"user": {
"alias1": null,
"alias2": null,
"alias3": null,
"alias4": null,
"aliases": {},
"created": 1721156264,
"email": "",
"enable_auto_prompt": true,
"firstname": "",
"is_enrolled": true,
"last_directory_sync": null,
"last_login": 1721245422,
"lastname": "",
"notes": "",
"realname": "",
"status": "active",
"user_id": "DABCDEFGHIJKL1MNOPQR",
"username": "rsanchez"
}
}
"stat": "OK"
}
Delete Desktop Authenticator
Delete the desktop authenticator with key dakey
from the system. Requires "Grant resource - Write" API permission to delete a desktop authenticator from a user.
DELETE /admin/v1/desktop_authenticators/[dakey]
Parameters
This API endpoint has no parameters.
Response Codes
Response | Meaning |
---|---|
200 | The desktop authenticator with key dakey was deleted. |
404 | No desktop authenticator was found with the given dakey . |
Response Format
Empty string.
Example Response
{
"response": "",
"stat": "OK",
}
Bypass Codes
Per-user Bypass Code Operations
See Create Bypass Codes for User and Retrieve Bypass Codes by User ID.
Retrieve Bypass Codes
Returns a paged list of information about all bypass codes. To fetch all results, call repeatedly with the offset
parameter as long as the result metadata has a next_offset
value. Output does not include the actual bypass codes. Requires "Grant resource - Read" API permission.
GET /admin/v1/bypass_codes
Parameters
Use the paging parameters to change the number of results shown in a response or to retrieve additional results. See Response Paging for details.
Paging Parameter | Required? | Description |
---|---|---|
limit
|
Optional |
The maximum number of records returned. Default: |
offset
|
Optional |
The offset from When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: |
This API endpoint has no additional parameters.
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
|
An integer indicating the expiration timestamp of the bypass code, or null if the bypass code does not expire on a certain date.
|
reuse_count
|
An integer indicating 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. See Retrieve Users for descriptions of the response fields. |
Example Response
{
"stat": "OK",
"response": [
{
"admin_email": "janesmith@example.com",
"bypass_code_id": "DB2A9F0012RL54001FA3",
"created": 1522260759,
"expiration": 1522264359,
"reuse_count": 1,
"user": {
"alias1": "joe.smith",
"alias2": "jsmith@example.com",
"alias3": null,
"alias4": null,
"aliases": {
"alias1": "joe.smith",
"alias2": "jsmith@example.com"
},
"created": 1384275337,
"email": "jsmith@example.com",
"enable_auto_prompt": true,
"external_id": "1a2345b6-7cd8-9e0f-g1hi-23j45kl6m789",
"firstname": "",
"is_enrolled": true,
"last_directory_sync": 1384275337,
"last_login": 1514922986,
"lastname": "",
"notes": "",
"realname": "Joe Smith",
"status": "active",
"user_id": "DU3RP9I2WOC59VZX672N",
"username": "jsmith"
}
]
}
Retrieve Bypass Code by ID
Return information about a single bypass code with bypass_code_id
. Output does not include the actual bypass code. Requires "Grant resource - Read" API permission.
GET /admin/v1/bypass_codes/[bypass_code_id]
Parameters
This API endpoint has no parameters.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
404 |
No bypass code was found with the given bypass_code_id .
|
Response Format
Returns a single bypass code object. Refer to Retrieve Bypass Codes for an explanation of the object's keys.
Example Response
{
"stat": "OK",
"response": {
"admin_email": "janesmith@example.com",
"bypass_code_id": "DB2A9F0012RL54001FA3",
"created": 1522260759,
"expiration": 1522264359,
"reuse_count": 1,
"user": {
"alias1": "joe.smith",
"alias2": "jsmith@example.com",
"alias3": null,
"alias4": null,
"aliases": {
"alias1": "joe.smith",
"alias2": "jsmith@example.com"
},
"created": 1384275337,
"email": "jsmith@example.com",
"enable_auto_prompt": true,
"external_id": "1a2345b6-7cd8-9e0f-g1hi-23j45kl6m789",
"firstname": "",
"is_enrolled": true,
"last_directory_sync": 1384275337,
"last_login": 1514922986,
"lastname": "",
"notes": "",
"realname": "Joe Smith",
"status": "active",
"user_id": "DU3RP9I2WOC59VZX672N",
"username": "jsmith"
}
}
}
Delete Bypass Code
Delete the bypass code with ID bypass_code_id
from the system. Requires "Grant resource - Write" API permission.
DELETE /admin/v1/bypass_codes/[bypass_code_id]
Parameters
This API endpoint has no parameters.
Response Codes
Response | 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
The Integrations v2 API does not use the same authentication and request signing detailed earlier in this document. Our Python, Go, Java, and Node.JS API clients have been updated with the new authentication and signing requirements and include support for the Integrations v2 API endpoints. We recommend you use the duo_client_python Python API client, the duo_api_golang Go API client, the duo_client_java Java API client, or the duo_api_nodejs Node.JS API client to interact with the Integrations v2 endpoints.
Retrieve Integrations
Returns a paged list of integrations. To fetch all results, call repeatedly with the offset
parameter as long as the result metadata has a next_offset
value. Requires "Grant resource - Read" API permission.
GET /admin/v2/integrations
Parameters
Use the paging parameters to change the number of results shown in a response or to retrieve additional results. See Response Paging for details.
Paging Parameter | Required? | Description |
---|---|---|
limit
|
Optional |
The maximum number of records returned. Default: |
offset
|
Optional |
The offset from When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: |
Response Codes
Response | Meaning |
---|---|
200 | Success. |
Response Format
Key | Value | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
adminapi_admins
|
Integer value of 1 if the integration has been granted permission for Administrators methods; otherwise 0 . Only applicable to Admin API integrations.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
adminapi_info
|
Integer value of 1 if the integration has been granted permission for Account Info methods; otherwise 0 . Only applicable to Admin API integrations.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
adminapi_integrations
|
Integer value of 1 if the integration has been granted permission for Integrations methods; otherwise 0 . Only applicable to Admin API integrations.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
adminapi_read_log
|
Integer value of 1 if the integration has been granted permission for Logs methods; otherwise 0 . Only applicable to Admin API integrations.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
adminapi_read_resource
|
Integer value of 1 if the integration has been granted permission to retrieve objects like users, phones, and hardware tokens; otherwise 0 . Only applicable to Admin API integrations.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
adminapi_settings
|
Integer value of 1 if the integration has been granted permission for Settings methods; otherwise 0 . Only applicable to Admin API integrations.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
adminapi_write_resource
|
Integer value of 1 if the integration has been granted permission to modify objects like users, phones, and hardware tokens; otherwise 0 . Only applicable to Admin API integrations.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
enroll_policy
|
Legacy parameter; no effect if specified and returns no value. Use Duo New User policies to configure this setting. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
frameless_auth_prompt_enabled
|
Integer value of 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 for that application, and the value is set to 1 automatically when Duo detects a frameless authentication for the integration.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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
|
Legacy parameter; no effect if specified and always returns an empty list. Use Duo Authorized Network policies to configure this for an application. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ip_whitelist_enroll_policy
|
Legacy parameter; no effect if specified and always returns no value. Use Duo Authorized Network policies to configure this for an application. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
missing_web_referer_policy |
Legacy parameter; no effect if specified and always returns deny. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
prompt_v4_enabled
|
Integer value of 1 if Duo Universal Prompt is activated for the application, otherwise 0 . Only appears for a given integration when frameless_auth_prompt_enabled is 1 (value set automatically when Duo detects a frameless authentication for the integration).
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
secret_key
|
Secret used when configuring systems to use this integration. The secret key will be hidden, showing only the last four characters. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
self_service_allowed
|
Integer value of 1 if users may use self-service from this integration's 2FA prompt to update authentication devices, otherwise false (default). Supported on integrations that display the interactive traditional Duo Prompt or the Duo Universal Prompt in a web broswer.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
sso
|
Information about your SSO integration. Only returned for SSO integrations. Refer to SSO Parameters for a list of valid values. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
trusted_device_days
|
Legacy parameter; no effect if specified and always returns no value. Use Duo Remembered Devices policies to configure this for an application. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
type
|
Integration type. One of
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
username_normalization_policy |
This controls whether or not usernames should be altered before trying to match them to a user account. Always blank for SSO integrations. One of:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
web_referers_enabled |
Integer value of 1 if allowed hostnames has been configured; otherwise 0 . Only configurable for integrations that still use the traditional Duo Prompt in an iframe. |
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": "",
"frameless_auth_prompt_enabled": 1,
"greeting": "Welcome to Duo.",
"groups_allowed": [],
"integration_key": "DIRWIH0ZZPV4G88B37VQ",
"ip_whitelist": [],
"ip_whitelist_enroll_policy": "",
"missing_web_referer_policy": "deny",
"name": "Generic SAML Service Provider",
"notes": "",
"policy_key": "POHSLA8SP00LABDAD98Y",
"prompt_v4_enabled": 1,
"secret_key": "************************************HazY7",
"self_service_allowed": false,
"sso": {
"idp_metadata": {
"cert": "-----BEGIN CERTIFICATE-----MIIDDTCCAfW...gAwIBAgIUAdARSAE-----END CERTIFICATE-----\n",
"entity_id": "https://sso-abc1def2.sso.duosecurity.com/saml2/idp/RI6WF1LHX9N8GBOEPGZR/metadata",
"metadata_url": "https://sso-abc1def2.sso.duosecurity.com/saml2/idp/RI6WF1LHX9N8GBOEPGZR/metadata",
"slo_url": "https://sso-abc1def2.sso.duosecurity.com/saml2/idp/RI6WF1LHX9N8GBOEPGZR/slo",
"sso_url": "https://sso-abc1def2.sso.duosecurity.com/saml2/idp/RI6WF1LHX9N8GBOEPGZR/sso"
},
"saml_config": {
"acs_urls": [],
"assertion_encryption_algorithm": null,
"attribute_transformations": [],
"encrypt_assertion": false,
"entity_id": "",
"key_transport_encryption_algorithm": null,
"mapped_attrs": {},
"nameid_attribute": "",
"nameid_format": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified",
"relaystate": null,
"remote_cert": null,
"role_attrs": {},
"sign_assertion": true,
"sign_response": true,
"signing_algorithm": "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256",
"slo_url": "",
"spinitiated_url": null,
"static_attrs": null
}
},
"trusted_device_days": 0,
"type": "websdk",
"username_normalization_policy": "None",
"web_referers_enabled": 0
},
{
"adminapi_admins": 0,
"adminapi_info": 0,
"adminapi_integrations": 0,
"adminapi_read_log": 1,
"adminapi_read_resource": 0,
"adminapi_settings": 0,
"adminapi_write_resource": 0,
"enroll_policy": "",
"greeting": "Welcome to Duo.",
"groups_allowed": [],
"integration_key": "DIRWIH0ZZPV4GJ05H7VQ",
"name": "Admin API",
"networks_for_api_access": "",
"notes": "",
"secret_key": "************************************HazY7",
"self_service_allowed": false,
"type": "adminapi",
"username_normalization_policy": "None",
}
]
}
Retrieve Integrations (Legacy v1)
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. This v1 API endpoint cannot retrieve Duo Single Sign-On applications and returns integrations' secret keys in plain text. Consider migrating to the v2 endpoint. Requires "Grant resource - Read" API permission.
GET /admin/v1/integrations
Parameters
Use the paging parameters to change the number of results shown in a response or to retrieve additional results. See Response Paging for details.
Paging Parameter | Required? | Description |
---|---|---|
limit
|
Optional |
The maximum number of records returned. Default: |
offset
|
Optional |
The offset from When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: |
This API endpoint has no additional parameters.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
Response Format
Key | Value | ||||||
---|---|---|---|---|---|---|---|
adminapi_admins
|
Integer value of 1 if the integration has been granted permission for Administrators methods; otherwise 0 . Only applicable to Admin API integrations.
|
||||||
adminapi_info
|
Integer value of 1 if the integration has been granted permission for Account Info methods; otherwise 0 . Only applicable to Admin API integrations.
|
||||||
adminapi_integrations
|
Integer value of 1 if the integration has been granted permission for Integrations methods; otherwise 0 . Only applicable to Admin API integrations.
|
||||||
adminapi_read_log
|
Integer value of 1 if the integration has been granted permission for Logs methods; otherwise 0 . Only applicable to Admin API integrations.
|
||||||
adminapi_read_resource
|
Integer value of 1 if the integration has been granted permission to retrieve objects like users, phones, and hardware tokens; otherwise 0 . Only applicable to Admin API integrations.
|
||||||
adminapi_settings
|
Integer value of 1 if the integration has been granted permission for Settings methods; otherwise 0 . Only applicable to Admin API integrations.
|
||||||
adminapi_write_resource
|
Integer value of 1 if the integration has been granted permission to modify objects like users, phones, and hardware tokens; otherwise 0 . Only applicable to Admin API integrations.
|
||||||
enroll_policy
|
Legacy parameter; no effect if specified and returns no value. Use Duo New User policies to configure this setting. |
||||||
frameless_auth_prompt_enabled
|
Integer value of 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 for that application, and the value is set to 1 automatically when Duo detects a frameless authentication for the integration.
|
||||||
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
|
Legacy parameter; no effect if specified and always returns an empty list. Use Duo Authorized Network policies to configure this for an application. |
||||||
ip_whitelist_enroll_policy
|
Legacy parameter; no effect if specified and always returns no value. Use Duo Authorized Network policies to configure this for an application. |
||||||
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. | ||||||
prompt_v4_enabled
|
Integer value of 1 if Duo Universal Prompt is activated for the application, otherwise 0 . Only appears for a given integration when frameless_auth_prompt_enabled is 1 (value set automatically when Duo detects a frameless authentication for the integration).
|
||||||
secret_key
|
Secret used when configuring systems to use this integration. | ||||||
self_service_allowed
|
Integer value of 1 if users may use self-service from this integration's 2FA prompt to update authentication devices, otherwise false (default). Supported integrations display the interactive Duo authentication prompt in a web browser.
Note: The v1 API response does not include information about Duo Single Sign-On applications. |
||||||
type
|
Integration type. Refer to Retrieve Integrations for a list of valid values.
Note: The v1 API response does not include information about Duo Single Sign-On applications. |
||||||
trusted_device_days
|
Legacy parameter; no effect if specified and always returns no value. Use Duo Remembered Devices policies to configure this for an application. |
||||||
username_normalization_policy
|
This controls whether or not usernames should be altered before trying to match them to a user account. One of:
|
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": "",
"frameless_auth_prompt_enabled": 1,
"greeting": "Welcome to Duo.",
"groups_allowed": [],
"integration_key": "DIRWIH0ZZPV4G88B37VQ",
"ip_whitelist": [],
"ip_whitelist_enroll_policy": "",
"name": "Web Application",
"notes": "",
"policy_key": "POHSLA8SP00LABDAD98Y",
"prompt_v4_enabled": 1,
"secret_key": "QO4ZLqQVRIOZYkHfdPDORfcNf8LeXIbCWwHazY7",
"self_service_allowed": false,
"trusted_device_days": 0,
"type": "websdk",
"username_normalization_policy": "None"
},
{
"adminapi_admins": 0,
"adminapi_info": 0,
"adminapi_integrations": 0,
"adminapi_read_log": 1,
"adminapi_read_resource": 0,
"adminapi_settings": 0,
"adminapi_write_resource": 0,
"enroll_policy": "",
"greeting": "Welcome to Duo.",
"groups_allowed": [],
"integration_key": "DIRWIH0ZZPV4GJ05H7VQ",
"name": "Admin API",
"networks_for_api_access": "",
"notes": "",
"secret_key": "QO4ZLqQVRIOZYkHfdPDORj05h8LeXIbCWwHazY7",
"self_service_allowed": false,
"type": "adminapi",
"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.
Note: This API call uses POST data, which must be represented as JSON and cannot be passed in via URL parameters. Some Duo clients (Python or Java, for example) offer helper functions to handle requests to the Admin API.
POST /admin/v2/integrations
Parameters
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. Duo Single Sign-On applications can only be created using the v2 endpoint. Integrations of type "azure-ca" (Microsoft Azure Active Directory) and "microsoft-eam" (Microsoft Entra ID: External Authentication Methods) may not be created via API. If an integration has reached the Duo end of support then new instances of that integration may not be created with the API. |
adminapi_admins
|
Optional |
Set to 1 to grant an Admin API integration permission for all Admins methods.
Default: 0 .
|
adminapi_info
|
Optional |
If creating an Admin API integration, set this to 1 to grant it permission for all Account Info methods.
Default: 0 .
|
adminapi_integrations
|
Optional |
Set to 1 to grant an Admin API integration permission for all Integrations methods.
Default: 0 .
|
adminapi_read_log
|
Optional |
Set to 1 to grant an Admin API integration permission for all Logs methods.
Default: 0 .
|
adminapi_read_resource
|
Optional |
Set to 1 to grant an Admin API integration permission to retrieve objects like users, phones, and hardware tokens.
Default: 0 .
|
adminapi_settings
|
Optional |
Set to 1 to grant an Admin API integration permission for all Settings methods.
Default: 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.
Default: 0 .
|
enroll_policy
|
Optional |
Legacy parameter; no effect if specified and returns no value. Use Duo New User policies to configure this setting. What to do after an unenrolled user passes primary authentication. |
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 |
Legacy parameter; no effect if specified and always returns an empty list. Use Duo Authorized Network policies to configure this for an application. |
ip_whitelist_enroll_policy
|
Optional |
Legacy parameter; no effect if specified and always returns no value. Use Duo Authorized Network policies to configure this for an application. What to do after a new user from a trusted IP completes primary authentication. |
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 Duo Admin Panel GUI. |
notes
|
Optional | Description of the integration. |
trusted_device_days
|
Optional |
Legacy parameter; no effect if specified and always returns |
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.
|
sso
|
Optional | If creating an SSO integration, refer to SSO parameters. |
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
Returns the created single integration object. Refer to Retrieve Integrations for an explanation of the object's keys.
Example Response
Same as Retrieve Integration by Integration Key.
Create Integration (Legacy v1)
Create a new integration. The new integration key and secret key are randomly generated and returned in the response. This v1 API endpoint cannot create Duo Single Sign-On applications and returns the integration's secret key in plain text. Consider migrating to the v2 endpoint. 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. Duo Single Sign-On applications can only be created using the v2 endpoint. Integrations of type "azure-ca" (Microsoft Azure Active Directory) "microsoft-eam" (Microsoft Entra ID: External Authentication Methods) may not be created via API. If an integration has reached the Duo end of support then new instances of that integration may not be created with the API. |
adminapi_admins
|
Optional |
Set to 1 to grant an Admin API integration permission for all Admins methods.
Default: 0 .
|
adminapi_info
|
Optional |
If creating an Admin API integration, set this to 1 to grant it permission for all Account Info methods.
Default: 0 .
|
adminapi_integrations
|
Optional |
Set to 1 to grant an Admin API integration permission for all Integrations methods.
Default: 0 .
|
adminapi_read_log
|
Optional |
Set to 1 to grant an Admin API integration permission for all Logs methods.
Default: 0 .
|
adminapi_read_resource
|
Optional |
Set to 1 to grant an Admin API integration permission to retrieve objects like users, phones, and hardware tokens.
Default: 0 .
|
adminapi_settings
|
Optional |
Set to 1 to grant an Admin API integration permission for all Settings methods.
Default: 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.
Default: 0 .
|
enroll_policy
|
Optional |
Legacy parameter; no effect if specified and returns no value. Use Duo New User policies to configure this setting. What to do after an unenrolled user passes primary authentication. |
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 |
Legacy parameter; no effect if specified and always returns an empty list. Use Duo Authorized Network policies to configure this for an application. |
ip_whitelist_enroll_policy
|
Optional |
Legacy parameter; no effect if specified and always returns no value. Use Duo Authorized Network policies to configure this for an application. What to do after a new user from a trusted IP completes primary authentication. |
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 Duo Admin Panel GUI. |
notes
|
Optional | Description of the integration. |
trusted_device_days
|
Optional |
Legacy parameter; no effect if specified and always returns |
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
Returns the created single integration object. Refer to Retrieve Integrations for an explanation of the object's keys.
Example Response
Same as Retrieve Integration by Integration Key.
Retrieve Integration by Integration Key
Return the single integration with integration_key
. Requires "Grant applications" API permission.
GET /admin/v2/integrations/[integration_key]
Parameters
This API endpoint has no parameters.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
404 | No integration was found with the given integration_key . |
Response Format
Returns the single integration object. Refer to Retrieve Integrations for an explanation of the object's keys.
Example Response
{
"stat": "OK",
"response": {
"adminapi_admins": 0,
"adminapi_info": 0,
"adminapi_integrations": 0,
"adminapi_read_log": 0,
"adminapi_read_resource": 0,
"adminapi_settings": 0,
"adminapi_write_resource": 0,
"enroll_policy": "",
"frameless_auth_prompt_enabled": 1,
"greeting": "Welcome to Duo.",
"groups_allowed": [],
"integration_key": "DIRWIH0ZZPV4G88B37VQ",
"ip_whitelist": [],
"ip_whitelist_enroll_policy": "",
"missing_web_referer_policy": "deny",
"name": "Generic SAML Service Provider",
"notes": "",
"policy_key": "POHSLA8SP00LABDAD98Y",
"prompt_v4_enabled": 1,
"secret_key": "************************************HazY7",
"self_service_allowed": false,
"sso": {
"idp_metadata": {
"cert": "-----BEGIN CERTIFICATE-----MIIDDTCCAfW...gAwIBAgIUAdARSAE-----END CERTIFICATE-----\n",
"entity_id": "https://sso-abc1def2.sso.duosecurity.com/saml2/idp/RI6WF1LHX9N8GBOEPGZR/metadata",
"metadata_url": "https://sso-abc1def2.sso.duosecurity.com/saml2/idp/RI6WF1LHX9N8GBOEPGZR/metadata",
"slo_url": "https://sso-abc1def2.sso.duosecurity.com/saml2/idp/RI6WF1LHX9N8GBOEPGZR/slo",
"sso_url": "https://sso-abc1def2.sso.duosecurity.com/saml2/idp/RI6WF1LHX9N8GBOEPGZR/sso"
},
"saml_config": {
"acs_urls": [],
"assertion_encryption_algorithm": null,
"attribute_transformations": [],
"encrypt_assertion": false,
"entity_id": "",
"key_transport_encryption_algorithm": null,
"mapped_attrs": {},
"nameid_attribute": "",
"nameid_format": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified",
"relaystate": null,
"remote_cert": null,
"role_attrs": {},
"sign_assertion": true,
"sign_response": true,
"signing_algorithm": "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256",
"slo_url": "",
"spinitiated_url": null,
"static_attrs": null
}
},
"trusted_device_days": 0,
"type": "websdk",
"username_normalization_policy": "None",
"web_referers_enabled": 0
}
}
Retrieve Integration by Integration Key (Legacy v1)
Return the single integration with integration_key
. This v1 API endpoint cannot retrieve Duo Single Sign-On applications and returns the integration's secret key in plain text. Consider migrating to the v2 endpoint. Requires "Grant applications" API permission.
GET /admin/v1/integrations/[integration_key]
Parameters
This API endpoint has no parameters.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
404 |
No integration was found with the given integration_key .
|
Response Format
Returns the single integration object. Refer to Retrieve Integrations for an explanation of the object's keys.
Example Response
{
"stat": "OK",
"response": {
"adminapi_admins": 0,
"adminapi_info": 0,
"adminapi_integrations": 0,
"adminapi_read_log": 0,
"adminapi_read_resource": 0,
"adminapi_settings": 0,
"adminapi_write_resource": 0,
"enroll_policy": "",
"frameless_auth_prompt_enabled": 1,
"greeting": "Welcome to Duo.",
"groups_allowed": [],
"integration_key": "DIRWIH0ZZPV4G88B37VQ",
"ip_whitelist": [],
"ip_whitelist_enroll_policy": "",
"name": "Web Application",
"notes": "",
"policy_key": "POHSL88SP00LABDAD98Y",
"prompt_v4_enabled": 1,
"secret_key": "QO4ZLqQVRIOZYkHfdPDORfcNf8LeXIbCWwHazY7",
"self_service_allowed": false,
"trusted_device_days": 0,
"type": "websdk",
"username_normalization_policy": "None"
}
}
Modify Integration
Change the name, greeting, and/or notes of the integration with integration key integration_key
, or reset its secret key. When modifying an Admin API integration permissions can also be added or removed. Requires "Grant applications" API permission.
Note: This API call uses POST data, which must be represented as JSON and cannot be passed in via URL parameters. Some Duo clients (Python or Java, for example) offer helper functions to handle requests to the Admin API.
POST /admin/v2/integrations/[integration_key]
Parameters
Parameter | Required? | Description |
---|---|---|
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 |
Legacy parameter; no effect if specified and always returns |
enroll_policy
|
Optional |
Legacy parameter; no effect if specified and returns no value. Use Duo New User policies to configure this setting. 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 |
Legacy parameter; no effect if specified and always returns an empty list. Use Duo Authorized Network policies to configure this for an application. Refer to Retrieve Integrations for a list of supported integrations. |
ip_whitelist_enroll_policy
|
Optional |
Legacy parameter; no effect if specified and always returns no value. Use Duo Authorized Network policies to configure this for an application. 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. |
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 Duo Admin Panel GUI. |
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. |
prompt_v4_enabled
|
Optional |
Set to 1 to activate Duo Universal Prompt for the application, or to 0 to revert back to traditional prompt. Only appears for a given integration when frameless_auth_prompt_enabled is 1 (value set automatically when Duo detects a frameless authentication for the 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. Can not be used with SSO applications. |
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.
|
sso
|
Optional | If modifying an SSO integration, refer to SSO parameters. |
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
Returns the modified single integration object. Refer to Retrieve Integrations for an explanation of the object's keys.
Example Response
Same as Retrieve Integration by Integration Key.
Modify Integration (Legacy v1)
Change the name, greeting, and/or notes of the integration with integration key integration_key
, or reset its secret key. When modifying an Admin API integration permissions can also be added or removed. This v1 API endpoint cannot modifyDuo Single Sign-On applications and returns the integration's secret key in plain text. Consider migrating to the v2 endpoint. 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 Duo 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 |
Legacy parameter; no effect if specified and always returns |
enroll_policy
|
Optional |
Legacy parameter; no effect if specified and returns no value. Use Duo New User policies to configure this setting. 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 |
Legacy parameter; no effect if specified and always returns an empty list. Use Duo Authorized Network policies to configure this for an application. Refer to Retrieve Integrations for a list of supported integrations. |
ip_whitelist_enroll_policy
|
Optional |
Legacy parameter; no effect if specified and always returns no value. Use Duo Authorized Network policies to configure this for an application. 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. |
prompt_v4_enabled
|
Optional |
Set to 1 to activate Duo Universal Prompt for the application, or to 0 to revert back to traditional prompt. Only appears for a given integration when frameless_auth_prompt_enabled is 1 (value set automatically when Duo detects a frameless authentication for the 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. Can not be used with SSO applications. |
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
Returns the modified single integration object. Refer to Retrieve Integrations for an explanation of the object's keys.
Example Response
Same as Retrieve Integration by Integration Key.
Delete Integration
Be sure to remove Duo authentication from your product's configuration before you delete the corresponding integration.
Depending on the application this could mean uninstalling Duo software from your systems, or updating your device or application settings to no longer include Duo in the authentication process.
There is no way to restore an integration deleted in error with Admin API.
Delete the integration with integration_key
from the system. Attempting to delete the Admin API integration whose secret key is used to sign this request will return an error. Requires "Grant applications" API permission.
DELETE /admin/v2/integrations/[integration_key]
Parameters
This API endpoint has no parameters.
Response Codes
Response | 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": ""
}
Delete Integration (Legacy v1)
Be sure to remove Duo authentication from your product's configuration before you delete the corresponding integration.
Depending on the application this could mean uninstalling Duo software from your systems, or updating your device or application settings to no longer include Duo in the authentication process.
There is no way to restore an integration deleted in error with Admin API.
Delete the integration with integration_key
from the system. Attempting to delete the Admin API integration whose secret key is used to sign this request will return an error.
This v1 API endpoint cannot delete Duo Single Sign-On applications.
Consider migrating to the v2 endpoint. Requires "Grant applications" API permission.DELETE /admin/v1/integrations/[integration_key]
Parameters
This API endpoint has no parameters.
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": ""
}
Retrieve Secret Key
Retrieve the skey
for the specified integration. Requires "Grant applications" API permission. Does not work for SSO integrations.
This endpoint does not use the same authentication and request signing detailed earlier in this document. Our Python, Go, Java, and Node.JS API clients have been updated with the new authentication and signing requirements and include support for this endpoint operation. We recommend you use the duo_client_python Python API client, the duo_api_golang Go API client, the duo_client_java Java API client, or the duo_api_nodejs Node.JS API client to perform this operation.
GET /admin/v1/integrations/[integration_key]/skey
Parameters
This API endpoint has no parameters.
Response Codes
Response | Meaning |
---|---|
200 | The skey was successfully returned. |
400 | No integration was found with the given integration_key . |
Response Format
Returns the skey
.
Example Response
{
"response": {
"skey": "Zh5eGmUq9zpfQnyUIu5OL9iWoMMv5ZNmk3zLJ4Ep"
},
"stat": "OK"
}
Retrieve Client Secret for an OAuth Integration
Retrieve the client_secret
for the specified OAuth integration. Requires "Grant applications" API permission.
GET /admin/v2/integrations/oauth_cc/[integration_key]/client_secret/[client_id]
Parameters
This API endpoint has no parameters.
Response Codes
Response | Meaning |
---|---|
200 | The client_secret was successfully returned. |
400 | Invalid parameters or no client was found with the given client_id . |
404 | No integration was found with the given integration_key . |
Response Format
Returns the client_secret
.
Example Response
{
"response": {
"client_secret": "Zh5eGmUq9zpfQnyUIu5OL9iWoMMv5ZNmk3zLJ4Ep"
},
"stat": "OK"
}
Reset Client Secret for an OAuth Integration
Reset the client_secret
for the specified OAuth integration. Requires "Grant applications" API permission.
POST /admin/v2/integrations/oauth_cc/[integration_key]/client_secret/[client_id]
Parameters
This API endpoint has no parameters.
Response Codes
Response | Meaning |
---|---|
200 | The client_secret was successfully reset. |
400 | Invalid parameters or no client was found with the given client_id . |
404 | No integration was found with the given integration_key . |
Response Format
Empty string.
Example Response
{
"response": {},
"stat": "OK"
}
Retrieve Client Secret for an OIDC Integration
Retrieve the client_secret
for the specified OIDC integration. Requires "Grant applications" API permission.
GET /admin/v2/integrations/oidc/[integration_key]/client_secret
Parameters
This API endpoint has no parameters.
Response Codes
Response | Meaning |
---|---|
200 | The client_secret was successfully returned. |
404 | No integration was found with the given integration_key . |
Response Format
Returns the client_secret
.
Example Response
{
"response": {
"client_secret": "Zh5eGmUq9zpfQnyUIu5OL9iWoMMv5ZNmk3zLJ4Ep"
},
"stat": "OK"
}
Reset Client Secret for an OIDC Integration
Reset the client_secret
for the specified OIDC integration. Requires "Grant applications" API permission.
POST /admin/v2/integrations/oidc/[integration_key]/client_secret
Parameters
This API endpoint has no parameters.
Response Codes
Response | Meaning |
---|---|
200 | The client_secret was successfully reset. |
404 | No integration was found with the given integration_key . |
Response Format
Empty string.
Example Response
{
"response": {},
"stat": "OK"
}
SSO Parameters
Parameter | Required? | Description | ||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idp_metadata |
Automatically generated | Provider information about Duo Single Sign-On.
|
||||||||||||||||||||||||||||||
oauth_config |
Required (if creating an OAuth 2.0 Client Credentials) | Values specific for OAuth 2.0 Client Credentials. See OAuth Parameters. | ||||||||||||||||||||||||||||||
oidc_config |
Required (if creating a Generic OIDC Relying Party) | Values specific for Generic OIDC Relying Party. See OIDC Parameters. | ||||||||||||||||||||||||||||||
saml_config |
Required (if creating a SAML integration) | Values specific for Generic SAML Service Provider. See SAML Parameters. |
OAuth Parameters
Parameter | Required? | Description | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
clients |
Required | List of clients. A client is a third-party application that wants to access a resource. Its privileges are limited by scopes.
|
||||||||||||||||||
scopes |
Required | List of scopes. Scopes are a mechanism to authorize a third-party application to perform only specific operations on behalf of the user.
|
OIDC Parameters
Parameter | Required? | Description | |||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
grant_types |
Required | Specify how a client gets an access or refresh token. A client can be configured to use more than one grant type.
|
|||||||||||||||||||||||||||
redirect_uris |
Required | List of redirection URIs to which the response will be sent. This URI can exactly match one of the redirection URI values the client pre-registered at the OpenID Provider or a URI with wildcard in subdomain can be used. | |||||||||||||||||||||||||||
scopes |
Required | Scopes are used by a client during authentication to authorize access to a user's details. Each scope returns a set of user attributes, which are called claims.
|
|||||||||||||||||||||||||||
claim_transformations |
Optional | List of transformed claims and rules for their transformations. |
SAML Parameters
Parameter | Required? | Description | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
acs_urls |
Required | List of URLs where your service provider receives SAML assertions. Each URL is an object with following parameters:
|
|||||||||||||||
entity_id |
Required | The service provider identifier. | |||||||||||||||
nameid_attribute |
Required | The authentication source attribute used to identify the user to the service provider. | |||||||||||||||
nameid_format |
Required | Format of NameID when sent to the service provider. | |||||||||||||||
sign_assertion |
Required | A boolean describing if SAML assertion will be signed. | |||||||||||||||
sign_response |
Required | A boolean describing if SAML response will be signed. | |||||||||||||||
signing_algorithm |
Required | Select the encryption strength supported by your service provider. The most common is SHA-256. | |||||||||||||||
assertion_encryption_algorithm |
Optional | Algorithm used for assertion encryption. | |||||||||||||||
attribute_transformations |
Optional | List of transformed IdP attributes and rules for their transformations. | |||||||||||||||
encrypt_assertion |
Optional | A boolean describing if SAML assertion will be encrypted. | |||||||||||||||
key_transport_encryption_algorithm |
Optional | Algorithm used for key transport encryption. | |||||||||||||||
mapped_attrs |
Optional | Dictionary of authentication source attributes mapped to the required names. | |||||||||||||||
relaystate |
Optional | If your service provider requires a specific RelayState parameter, enter it here. | |||||||||||||||
remote_cert |
Optional | Certificate for signing. | |||||||||||||||
role_attrs |
Optional | Dictionary of role attributes mapped to multiple roles. | |||||||||||||||
slo_url |
Optional | URL where your service provider receives SAML logout responses. | |||||||||||||||
spinitiated_url |
Optional | URL provided by your service provider that will start a SAML authentication. | |||||||||||||||
static_attrs |
Optional | Dictionary of new attributes mapped to hard coded static attributes. |
Policies
The Policies v2 API does not use the same authentication and request signing detailed earlier in this document. Our Python, Go, Java, and Node.JS API clients have been updated with the new authentication and signing requirements and include support for the Policies v2 API endpoints. We recommend you use the duo_client_python Python API client, the duo_api_golang Go API client, the duo_client_java Java API client, or the duo_api_nodejs Node.JS API client to interact with the Policies endpoints.
Summarize Policies
Returns policy names, keys, and applications or groups to which a policy is applied. Requires "Grant resource - Read" API permission.
GET /admin/v2/policies/summary
Parameters
This API endpoint has no parameters.
Response Codes
Response | Meaning |
---|---|
200 | Success. Returns all policies for the account and where they are applied (unless response is truncated). |
400 | Invalid or missing parameters. |
Response Format
Key | Value | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
policies
|
An array of policy blocks, each containing a
|
||||||||||||||||||||
policy_count
|
The total number of policies in this account. |
||||||||||||||||||||
response_is_truncated
|
True if the response has been truncated due to too much data being returned. Otherwise false (default). The response for this call cannot be paged and will be truncated if too much data is returned. |
||||||||||||||||||||
warnings
|
Contains non-fatal failures & warnings. |
Example Response
{
"policies": [
{
"policy_applies_to": [
{
"app_integration_key": "DI29C05TCOFOX9QFZEKI",
"app_name": "Acme Corp Office 365",
"apply_type": "group_app",
"group_position": "0",
"groups": [
{
"group_id": "DGC00OELIG7CQD5AV958",
"group_name": "Contractors"
}
]
}
],
"policy_key": "PO0LORUX8W6GXFX27HR0",
"policy_name": "12 hours Remembered Devices"
},
{
"policy_applies_to": [
{
"app_integration_key": "DI29C05TCOFOX9QFZEKI",
"app_name": "Acme Corp Office 365",
"apply_type": "app"
}
],
"policy_key": "PO0LBA709Z49E5XCHW06",
"policy_name": "7 Days Remembered Devices"
},
{
"policy_applies_to": [
{
"app_integration_key": "DI38Z0OPBEO4G8WE56OV",
"app_name": "Acme Cisco VPN",
"apply_type": "app"
},
{
"app_integration_key": "DION2T45OKE14FSYN4HN",
"app_name": "Windows Remote Desktop",
"apply_type": "app"
}
],
"policy_key": "POAWMUK0XYZQ6BUPBEJF",
"policy_name": "Deny All Unenrolled Users"
},
{
"policy_applies_to": [],
"policy_key": "PO9HIT6SE6TWQPVYZD6A",
"policy_name": "Bypass MFA and Allow Unenrolled"
},
{
"policy_applies_to": [
{
"app_integration_key": "DILSVDEYH66ZT8KIXGR9",
"app_name": "Acme Corp Office 365",
"apply_type": "group_app",
"group_position": "1",
"groups": [
{
"group_id": "DGIKLVP7LVU968UCDPVJ",
"group_name": "Verified Push Users"
}
]
}
],
"policy_key": "POWD3Z4WJIE3CF48A33K",
"policy_name": "Verified Push"
}
],
"policy_count": 5,
"response_is_truncated": false,
"warnings": [
"Policy 'Bypass MFA and Allow Unenrolled' is not applied to any groups or applications"
]
},
"stat": "OK"
}
Retrieve Policies
Retrieve a complete set of all policies. Includes all policy section data for each policy. Requires "Grant resource - Read" API permission.
GET /admin/v2/policies
Parameters
Use the paging parameters to change the number of results shown in a response or to retrieve additional results. See Response Paging for details.
Paging Parameter | Required? | Description |
---|---|---|
limit
|
Optional |
The maximum number of records returned. Default: |
offset
|
Optional |
The offset from When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: |
This API endpoint has no additional parameters.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
400 | Invalid or missing parameters. |
Response Format
Returns a JSON array of policy objects. Refer to Retrieve Policy by ID for an explanation of the policy object's keys and values. See Policy Section Data for descriptions of all policy section data keys and values.
Example Response
[
{
"policy_name": "Global Policy",
"policy_key": "POMY5S1FW9345IEM33BK",
"is_global_policy": true,
"sections": {
# Policy Section data appears here
# See "Policy Section Data" in this document for more information.
}
},
{
"policy_name": "Contractor Policy",
"policy_key": "POMY5S1FW93239EM33BK",
"is_global_policy": false,
"sections": {
# Policy Section data appears here
# See "Policy Section Data" in this document for more information.
}
}
]
Retrieve Policy by ID
Return the single policy with the specified policy_key
. Use global
as a shortcut for the global policy. Includs all policy section data. Requires "Grant resource - Read" API permission.
GET /admin/v2/policies/[policy_key]
GET /admin/v2/policies/global
Parameters
This API endpoint has no parameters.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
400 | Invalid or missing parameters. |
404 |
No policy was found with the given policy_key .
|
Response Format
Returns a single policy object.
Key | Value | ||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
is_global_policy
|
True if this policy is the global policy. Otherwise false (default). The value for this key cannot be changed. |
||||||||||||||||||||||||||||||||||||||
policy_applies_to
|
An array of all applications, and groups within applications, to which the policy is applied. If the groups |
||||||||||||||||||||||||||||||||||||||
policy_key
|
The identifier for the policy: 20 alphanumeric characters starting with “PO”, or “global” as a shortcut for the global policy. The value for this key cannot be changed. |
||||||||||||||||||||||||||||||||||||||
policy_name
|
Name of the custom policy, or "Global Policy" for the global policy. Policy names do not have to be unique. This key was previously |
||||||||||||||||||||||||||||||||||||||
sections
|
The list of all enabled policy sections for the policy_key, with associated keys/values for each section. Each section here corresponds to a named section that appears when editing the policy in the Admin Panel. See Policy Section Data for information on all available sections, keys, and values.
The number of sections available will vary based on which Duo edition you have.
|
Section Data
See Policy Section Data for descriptions of all policy section data keys and values.
Resulting Policy
Returns the resulting policy for a given user/application pair. The resulting policy is constructed from the top-most sections from the entire stack of policies applied for a given ikey
. Requires "Grant resource - Read" API permission.
GET /admin/v2/policies/calculate
Parameters
Parameter | Required? | Description |
---|---|---|
user_id
|
Required |
The |
integration_key
|
Required |
The |
Response Codes
Response | Meaning |
---|---|
200 |
Success. The resulting policy information is returned in the response. |
400 |
Invalid or missing parameters. |
Response Format
Returns information about the resulting policy. The sections
key has the same format as policy section data returned from other Policies endpoints. See Policy Section Data for descriptions of all policy section data keys and values.
Key | Value | ||||||||
---|---|---|---|---|---|---|---|---|---|
policy_elements
|
A list of policies that were combined to form the resulting policy. This list is ordered according to the order of precedence used to determine the resulting policy, with the highest precedence policy coming first. Each entry in the list contains the following information:
|
||||||||
sections
|
Policy Section Data from the resulting policy. |
Example Response
{
"policy_elements": [
{
"policy_key": "POLK595BO6OY8OK565I0",
"policy_name": "Contractor Policy",
"policy_type": "group"
},
{
"policy_key": "POFLZVHVBOKR23D4N2F0",
"policy_name": "Web App Policy",
"policy_type": "application"
},
{
"policy_key": "POCAZZJBRUUR4Q4DQ388",
"policy_name": "Global Policy",
"policy_type": "global"
}
],
"sections": {
# Policy section data appears here
},
}
Copy Policy
Copies the specified policy to one or more new custom policies. The new policies created by the call will contain the same settings as the copied policy, but will not be applied anywhere. Use Update Policy to apply the new policies to applications or groups within apps. Requires "Grant resource - Write" API permission.
Note: This API call uses POST data, which must be represented as JSON and cannot be passed in via URL parameters. Some Duo clients (Python or Java, for example) offer helper functions to handle requests to the Admin API.
POST /admin/v2/policies/copy
Parameters
Parameter | Required? | Description |
---|---|---|
policy_key
|
Required |
The identifier for an existing policy to be copied: 20 alphanumeric characters starting with |
new_policy_names_list
|
Optional |
An array of policy names. The policy specified by |
Response Codes
Response | Meaning |
---|---|
200 |
Success. |
400 |
Invalid or missing parameters. |
404 |
Policy key specified does not exist. |
Response Format
Returns the new policies.
Example Response
{
"policies": [ {
"policy_name": "Policy Name",
"policy_key": "PO239847239H41344KIN",
"is_global_policy": false,
"sections": {
# Section Data that was changed appears here
}
},
{
"policy_name": "some policy name 2",
"policy_key": "POMY5S1FW92342EM33BK",
"is_global_policy": false,
"sections": { }
} ],
"warnings": [ ]
}
Create Policy
Creates a new custom policy with the policy_name
specified in the parameters. Requires "Grant resource - Write" API permission.
Note: This API call uses POST data, which must be represented as JSON and cannot be passed in via URL parameters. Some Duo clients (Python or Java, for example) offer helper functions to handle requests to the Admin API.
POST /admin/v2/policies
Parameters
Parameter | Required? | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
policy_name
|
Required |
The name of the policy to create. Policy names do not have to be unique. The |
||||||||||
apply_to_apps
|
Optional |
Application assignment information for the new policy.
|
||||||||||
apply_to_groups_in_apps
|
Optional |
Information about which groups (within which applications) to which to apply the policy. See Applying Policy to Groups for more information on constructing a list of group policies to affect.
|
||||||||||
sections
|
Optional |
The list of policy sections to be added, with associated keys/values for each section. See Policy Section Data for all sections and their keys/values. |
Response Codes
Response | Meaning |
---|---|
200 |
Success. The newly-created policy’s unique key appears in the response. |
400 |
Invalid or missing parameters. |
Response Format
Returns the new policy object.
Example Response
The sections
block will be blank on a newly-created policy if no sections were specified in the "Create Policy" call. Use Update Policy to change an existing policy’s name, add or remove policy sections, and update keys and values.
{
"policy_applies_to": [
{
"app_integration_key": "DI0SUYB00VPUJWGWC2SH",
"app_name": "Acme Web App",
"apply_type": "app"
}
],
"policy_name": "New Policy",
"policy_key": "POMY5S1FW9345IEM33BK",
"is_global_policy": false,
"sections": {
# Section Data appears here if it was included in the Create Policy call.
# See "Policy Section Data" in this document for more information.
},
"warnings": [
]
}
Update Policies
Update policy section data for all policies or a set of specified policy_key
values. Requires "Grant resource - Write" API permission.
Note: This API call uses the PUT request method, which must be represented as JSON and cannot be passed in via URL parameters. Some Duo clients (Python or Java, for example) offer helper functions to handle requests to the AdminAPI.
PUT /admin/v2/policies/update
Parameters
Parameter | Required? | Description | ||||||||
---|---|---|---|---|---|---|---|---|---|---|
policies_to_update
|
Required |
The list of policies to update.
|
||||||||
policy_changes
|
Required |
The list of changes to apply to the policies specified in
|
Response Codes
Response | Meaning |
---|---|
200 |
One or more policies were modified successfully. The updated policies are also returned. |
400 |
Invalid or missing parameters. |
Response Format
Returns the updated policy objects and the full set of applications and/or groups to which each one is applied.
See Policy Section Data for an explanation of the object's keys/values shown in the sections
block. Refer to Summarize Policies for a complete listing of all keys in the policy_applies_to
block.
Example Response
{
"policies": [{
"policy_name": "Policy 1",
"policy_key": "PO239847239H41344KIN",
"is_global_policy": false,
"sections": {
# Section Data that was changed appears here
},
"policy_applies_to": [{ }]
},
{
"policy_name": "Policy 2",
"policy_key": "POMY5S1FW92342EM33BK",
"sections": {},
"policy_applies_to": [{
# format for policies that are applied to groups within an app
"app_name": "Acme Corp",
"app_integration_key": "DIRWIH0ZZPV8GJ05H7RM",
"apply_type": "group_app",
"group_position": "1",
"groups": [{
"group_name": "RBA Users",
"group_id": "DGPDO71QEP8Q03B9C59S"
},
{
"group_name": "API Users",
"group_id": "DGPDO7F00P8Q03B9C59S"
} ]
} ],
"warnings": [
# warnings include:
# "Update: Unrecognized section: <unknown-section> in $POLICY"
# "Update: Unknown section to delete: <bogus-section> in $POLICY"
# "Update: Policy (or key) $ID does not exist"
]
} ]
}
Update Policy
For the policy with the specified policy_key
, update policy data and add or change how the policy is applied. Requires "Grant resource - Write" API permission.
What happens if I...
-
Make the Update Policy call without one or more of the parameters describing what to modify:
sections
,sections_to_delete
,apply_to_apps
, orapply_to_groups_in_apps
?- The API call makes the changes you specify in the input, but all the parameters are optional.
- If you make the call with no changes in any of the parameters, the call returns the (unchanged) policy.
-
Add a policy
section
(such asauthorized_networks
) to a custom policy?- The API enables the section (that is, makes it active in the policy) and sets the valid values you specify. Any key/value pairs not specified for the section will be set to their default values.
- If you add a blank policy section, it will be enabled for the policy with default values.
-
Modify values for an existing policy
section
?- The API changes only the values you specify.
Note: This API call uses the PUT request method. The data passed in must be represented as JSON and cannot be passed in via URL parameters. Some Duo clients (Python or Java, for example) offer helper functions to handle requests to the Admin API.
PUT /admin/v2/policies/[policy_key]
Parameters
Parameter | Required? | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
apply_to_apps |
Optional | Application assignment information for the new policy.
|
||||||||||||
apply_to_groups_in_apps |
Optional | Information about which groups (within which applications) to which to apply the policy. See Applying Policy to Groups for more information on constructing a list of group policies to affect.
|
||||||||||||
policy_name |
Optional |
A new name for a custom policy. Policy names do not have to be unique. The |
||||||||||||
sections |
Optional |
The list of policy sections to be added, with associated keys/values for each section. See Policy Section Data for all sections and their keys/values. If |
||||||||||||
sections_to_delete |
Optional | An array of section names to remove from this policy. Sections cannot be removed from the global policy. |
Applying Policy to Groups
Because policy is applied to and unassigned from groups in the context of an application (integration
), you will need to specify both an app_integration_key
and an array of groups (group_id_list
) when applying policy to groups.
Key | Value |
---|---|
app_integration_key
|
The unique identifier for the application (same value as |
group_id_list
|
An array of unique group identifiers. See the response to Retrieve Groups to find |
Example Input
In this example, the "Update Policy" input will remove group policy assignments.
{
"apply_to_groups_in_apps": {
"unassign_group_policies_list": [ {
"app_integration_key": "DIRWIH0ZZPV4GJ05H7VQ",
"group_id_list": ["DGBDKSSH37KSJ373JKSU", "DGJKSLSH393YSJD93HSD3"]
},
{
"app_integration_key": "DIRWIH0ZZPV4GJ05H7HQ",
"group_id_list": ["DGBDKSSH37KSJ373JKSU", "DGJKSLSH393YSJD93HSD3"]
} ]
}
}
Response Codes
Response | Meaning |
---|---|
200 |
The policy was modified successfully. The policy object is also returned. |
400 |
Invalid or missing parameters. |
404 |
Policy key specified does not exist. |
Response Format
Returns the updated policy object and the full set of associated applications and/or groups.
See Policy Section Data for descriptions of all policy section data keys and values shown in the sections
block. Refer to Summarize Policies for a complete listing of all keys in the policy_applies_to
block.
Example Response
{
"is_global_policy": false,
"policy_key": "POMY5S1FW92342EM33BK",
"policy_name": "Modified Policy Name",
"policy_applies_to": [
{
"app_integration_key": "DILSVDEYH6Z008KIXGR9",
"app_name": "Acme Corp",
"apply_type": "group_app",
"group_position": "2",
"groups": [
{
"group_id": "DGPDO71QEP8Q03B9C59S",
"group_name": "RBA Users"
}
]
},
{
"app_integration_key": "DI1K3PT8F00DU4Y9IX0I",
"app_name": "Acme Auth API",
"apply_type": "group_app",
"group_position": "0",
"groups": [
{
"group_id": "DGPDO7F00P8Q03B9C59S",
"group_name": "API Users"
}
]
},
"sections": {
# Section Data changed appears here.
# See "Policy Section Data" in this document for more information.
},
"warnings": [
# Contains non-fatal failures and warnings such as misspelled section names.
]
}
Delete Policy
Delete the entire custom policy identified by policy_key
from the system. Requires "Grant resource - write" API permission.
Warning: Policies deleted using this call are immediately and permanently removed from Duo.
To delete policy sections from a custom policy, use an Update Policy call and specify the section(s) in sections_to_delete
.
DELETE /admin/v2/policies/[policy_key]
Parameters
This API endpoint has no parameters.
Response Codes
Response | Meaning |
---|---|
200 | The custom policy was deleted. |
400 | Invalid parameters. |
404 | The specified custom policy does not exist. |
Response Format
Empty string.
Example Response
{
"stat": "OK",
"response": ""
}
Policy Section Data
Policy sections are used in constructing Create Policy and Update Policy calls. They are also returned as part of the system response to Retrieve Policies, Retrieve Policy by ID, Create Policy, and Update Policy calls.
The API policy sections
correspond to the named sections visible in the Duo Admin Panel policy editor, as described in the Retrieve Policy by ID "Response Format" section.
We've noted when a specific Duo edition is required to access a section or to enable some keys or values in the section descriptions below.
Anonymous Networks
Section Name: anonymous_networks
Corresponds to: Anonymous Networks
This section is available in the Premier and Advantage editions.
Key | Value |
---|---|
anonymous_access_behavior
|
Defines what happens when a user on an anonymous network attempts to access resources. One of |
Authentication Methods
Section Name: authentication_methods
Corresponds to: Authentication Methods
Key | Value |
---|---|
allowed_auth_list
|
Comma-separated list of allowed authentication methods. The list defaults to: |
auto_retry_sms
|
Is |
blocked_auth_list
|
Comma-separated list of blocked authentication methods. The list defaults to: |
require_verified_push
|
Is |
verified_push_digits
|
The number of digits a verified push requires the user to enter. An integer between |
Authentication Policy
Section name: authentication_policy
Corresponds to: Authentication Policy
Key | Value |
---|---|
user_auth_behavior
|
Defines the behavior when a user authenticates. One of:
|
Authorized Networks
Section Name: authorized_networks
Corresponds to: Authorized Networks
Key | Value | ||||||
---|---|---|---|---|---|---|---|
no_2fa_required
|
Networks the user can access with no 2FA required.
|
||||||
mfa_required
|
Networks the user can access that require MFA. This key is available in the Premier and Advantage editions.
|
||||||
deny_other_access
|
Is |
Browsers
Section Name: browsers
Corresponds to: Browsers
This section is available in the Premier and Advantage editions.
Key | Value |
---|---|
allowed_browsers_list
|
Comma-separated list of allowed browsers. Any of: Default behavior permits all browsers. |
blocked_browsers_list
|
Comma-separated list of blocked browsers. Any of: Default: none. |
out_of_date_behavior
|
Value is one of |
browser_max_ood_days
|
The number of days that a browser may be out of date before access to it is blocked ( |
Duo Desktop
Section Name: duo_desktop
Corresponds to: Duo Desktop
This section affects applications protected by Duo Desktop. Duo Desktop was called Duo Device Health (device_health_app
) prior to November 2023.
Key | Value |
---|---|
requires_duo_desktop
|
Comma-separated list of operating systems that require Duo Desktop (one or more of |
prompt_to_install
|
Legacy key; no effect if specified. |
bypass_encryption_for_vm
|
(Early Access) Comma-separated list of operating systems that will allow the disk encryption, FileVault, or BitLocker check to be bypassed for virtual machines (one or more of |
enforce_device_id_pinning
|
Set to |
enforce_encryption
|
Comma-separated list of operating systems that will require the hard drive to be encrypted (one or more of |
enforce_firewall
|
Comma-separated list of operating systems that will require a firewall to be active (one or more of |
enforce_signed_payload
|
Set to |
enforce_system_password
|
Comma-separated list of operating systems that will require a system password to be set (one or more of |
linux_endpoint_security_list
|
Comma-separated list of Duo-supported endpoint security agents that are allowed. For agents in this list, the application will block access unless one of those agents is running. A complete list of Linux security agents is available in a drop-down when editing the policy in the Admin Panel. This key is available in the Premier edition. |
linux_remediation_note
|
A text note (max 700 characters) with remediation instructions when an end user is blocked. This key is available in the Premier edition. |
macos_endpoint_security_list
|
Comma-separated list of Duo-supported endpoint security agents that are allowed. For agents in this list, the application will block access unless one of those agents is running. A complete list of macOS security agents is available in a drop-down when editing the policy in the Admin Panel. This key is available in the Premier edition. |
macos_remediation_note
|
A text note (max 700 characters) with remediation instructions when an end user is blocked. This key is available in the Premier edition. |
windows_endpoint_security_list
|
Comma-separated list of Duo-supported endpoint security agents that are allowed. For agents in this list, the application will block access unless one of those agents is running. A complete list of Windows security agents is available in a drop-down when editing the policy in the Admin Panel. This key is available in the Premier edition. |
windows_remediation_note
|
A text note (max 700 characters) with remediation instructions when an end user is blocked. This key is available in the Premier edition. |
Duo Mobile App
Section Name: duo_mobile_app
Corresponds to: Duo Mobile App
This section is available in the Premier and Advantage editions.
Key | Value |
---|---|
block_policy |
Indicates when the user will be blocked from authenticating. Value is one of:
|
block_remediation_days |
The number of days before the user will be blocked. Value is one of |
block_version |
The specific Duo Mobile app version (from the list in the edit policy UI) that is being blocked. The default is |
require_updates |
(Deprecated) Is |
warn_policy |
Indicates when the user should be warned that their Duo Mobile app is out of date. Value is one of:
|
warn_remediation_days |
The number of days that the user will be warned. Value is one of |
warn_version |
The specific Duo Mobile version (from the list in the edit policy UI) subject to the out-of-date warning. Applicable only if |
Full Disk Encryption
Section Name: full_disk_encryption
Corresponds to: Full Disk Encryption
This section is available in the Premier and Advantage editions.
Key | Value |
---|---|
require_encryption
|
Is |
Mobile Device Biometrics
Section Name: mobile_device_biometrics
Corresponds to: Mobile Device Biometrics
This section is available in the Premier and Advantage editions.
Key | Value |
---|---|
block_biometric_pin_fallback
|
Is |
require_biometrics
|
Is |
New User Policy
Section Name: new_user
Corresponds to: New User Policy
Key | Value |
---|---|
new_user_behavior
|
Controls what happens after an unenrolled user passes primary authentication. One of:
|
Operating Systems
Section Name: operating_systems
Corresponds to: Operating Systems
This section is available in the Premier and Advantage editions.
The operating_systems
section affects devices used to access applications protected by Duo's browser-based authentication prompt, and mobile devices using Duo Mobile as a second factor.
The operating system names that can be in each of the lists below are: android
, blackberry
, chromeos
, ios
, linux
, macos
, windows
, windowsphone
, and unknownos
.
Note: No operating system should be listed in more than one of allow_unrestricted_os_list
, block_os_list
, and os_restrictions
. In the case of conflicts, the API call will fail.
Key | Value | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
allow_unrestricted_os_list
|
Comma-separated list of operating systems that are allowed with no constraints or warnings. |
||||||||||||||
block_os_list
|
Comma-separated list of operating systems that are not allowed. |
||||||||||||||
os_restrictions
|
Can contain up to 4 blocks of keys – one for each operating system that can be further restricted:
Example section: Warn for two weeks if iOS is not up to date; block after 60 days total.
|
Plugins
Section Name: plugins
Corresponds to: Plugins
This section is available in the Premier and Advantage editions.
Key | Value |
---|---|
flash
|
Specify how Flash plugins are treated. Value is one of |
java
|
Specify how Java plugins are treated. Value is one of:
|
java_max_ood_days
|
The number of days that Java plugins may be out of date before access is blocked ( |
Remembered Devices
Section Name: remembered_devices
Corresponds to: Remembered Devices
This section affects how and when users can skip subsequent 2FA and Duo Passwordless (if enabled) login requests.
Note: Passwordless users will be able to remember devices for no longer than three days, regardless of the selected length of time entered via max_time_units
and max_time_value
.
Key | Value | ||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
browser_apps
|
|
||||||||||||||||||||||||
windows_logon
|
|
Risk-Based Factor Selection
Section Name: risk_based_factor_selection
Corresponds to: Risk-Based Factor Selection
This section is available in the Premier and Advantage editions.
To enable these policy settings, applications must have the Universal Prompt activated or use the named "Duo Auth API" application. Learn more about requirements for these policy settings.
Key | Value |
---|---|
limit_to_risk_based_auth_methods
|
Is |
risk_based_verified_push_digits
|
The number of digits a verified push requires the user logging in to enter. An integer between |
Screen Lock
Section Name: screen_lock
Corresponds to: Screen Lock
This section is available in the Premier and Advantage editions.
Key | Value |
---|---|
require_screen_lock
|
Is |
Tampered Devices
Section Name: tampered_devices
Corresponds to: Tampered Devices
This section is available in the Premier and Advantage editions.
Key | Value |
---|---|
block_tampered_devices
|
Is |
Trusted Endpoints
Section Name: trusted_endpoints
Corresponds to: Trusted Endpoints
A trusted endpoint is an endpoint that exists in a management system such as your EAM or MDM. It can be matched to your management system using Duo certificates or information provided by the Duo Mobile app.
Key | Value |
---|---|
trusted_endpoint_checking
|
Value is one of |
cisco_secure_endpoint_can_block
|
Is |
trusted_endpoint_checking_mobile
|
Allowed values and default are the same as |
User Location
Section Name: user_location
Corresponds to: User Location
This section is available in the Premier and Advantage editions.
Obtain Alpha-2 country codes from https://www.iso.org/obp/. Choose Country Codes and then Search to see the list of country codes.
Key | Value |
---|---|
require_mfa_countries_list
|
List of one or more country codes. If the user’s location matches one of the codes, that user is required to use MFA to authenticate. |
deny_access_countries_list
|
List of one or more country codes. If the user’s location matches one of the codes, that user is denied access. |
allow_access_no_2fa_countries_list
|
List of one or more country codes. If the user’s location matches one of the codes, that user is allowed access without 2FA. |
ignore_location_countries_list
|
List of one or more country codes. If the user’s location matches one of the codes, no action is taken. |
default_action
|
Indicates behavior for country codes that aren’t in any list. Values are one of:
|
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 resource - Read" API permission.
Information for a given endpoint is purged after 30 days of inactivity.
Endpoint information retrievable by Duo Premier and Duo Advantage customers. In addition, some response information is available only with Duo Premier.
GET /admin/v1/endpoints
Parameters
Use the paging parameters to change the number of results shown in a response or to retrieve additional results. See Response Paging for details.
Paging Parameter | Required? | Description |
---|---|---|
limit
|
Optional |
The maximum number of records returned. Default: |
offset
|
Optional |
The offset from When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: |
This API endpoint has no additional parameters.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
Response Format
Key | Value | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
browsers
|
Collected information about all detected browsers on an individual endpoint.
|
||||||||||||
computer_sid
|
The machine security identifier of a Windows endpoint. | ||||||||||||
cpu_id
|
The CPU ID of a Windows endpoint. | ||||||||||||
device_id
|
Custom device identifier of a Meraki-managed iOS endpoint. Returned for Duo Premier customers only. | ||||||||||||
device_identifier
|
The unique device attribute value that identifies the endpoint. Returned for Duo Premier customers only. This property will be deprecated in a future release. | ||||||||||||
device_identifier_type
|
The device attribute used to identify a unique endpoint. One of "hardware_uuid", "fqdn", "hardware_serial", "device_udid", or none. This property will be deprecated in a future release. | ||||||||||||
device_name
|
The endpoint's hostname. | ||||||||||||
device_udid
|
The unique device identifier for iOS endpoints managed by Workspace ONE, Ivanti Endpoint Manager Mobile, Ivanti Neurons for MDM, or Sophos Mobile via certificates. Returned for Duo Premier customers only. | ||||||||||||
device_username
|
The unique attribute value that identifies the endpoint's associated user in the management system. Returned for Duo Premier 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 Premier customers only. | ||||||||||||
disk_encryption_status
|
The hard drive encryption status of the endpoint as detected by Duo Desktop. One of "On", "Off", or "Unknown". | ||||||||||||
domain_sid
|
The Active Directory domain security identifier for a domain-joined Windows endpoint. Empty if the Windows endpoint is not joined to a domain. | ||||||||||||
email
|
The email address, if present, of the user associated with an endpoint. | ||||||||||||
epkey
|
The endpoint's unique identifier. Most reliable when reported by Duo Desktop installed on the endpoint. | ||||||||||||
firewall_status
|
Status of the endpoint's local firewall as detected by Duo Desktop. One of "On", "Off", or "Unknown". | ||||||||||||
hardware_uuid
|
The universally unique identifier for a Mac endpoint. | ||||||||||||
health_app_client_version
|
The version of Duo Desktop installed on the endpoint. | ||||||||||||
health_data_last_collected
|
The last time Duo Desktop performed a device health check, as a Unix timestamp. | ||||||||||||
last_updated
|
The last time the endpoint accessed Duo, as a Unix timestamp. | ||||||||||||
machine_guid
|
The globally unique identifier for a Windows or macOS endpoint. | ||||||||||||
model
|
The device model of a 2FA endpoint. | ||||||||||||
os_build
|
The endpoint's operating system build number. | ||||||||||||
os_family
|
The endpoint's operating system platform. | ||||||||||||
os_version
|
The endpoint's operating system version. | ||||||||||||
password_status
|
Whether the local admin password is set on the endpoint as detected by Duo Desktop. One of "Set", "Unset", or "Unknown". | ||||||||||||
security_agents
|
Information about security agents present on the endpoint as detected by Duo Desktop. Returned for Duo Premier customers only.
|
||||||||||||
trusted_endpoint
|
Whether the endpoint is a Duo managed endpoint. One of "yes", "no", or "unknown". | ||||||||||||
type
|
The endpoint's device class. | ||||||||||||
username
|
The Duo username of the user associated with an endpoint. |
Example Response
Example response for a Duo Premier plan customer
{
"stat": "OK",
"response": [{
"browsers": [{
"browser_family": "Chrome",
"browser_version": "91.0.4472.77",
"flash_version": "uninstalled",
"java_version": "uninstalled",
"last_used": 1624451420
},
{
"browser_family": "Safari",
"browser_version": "14.1",
"flash_version": "uninstalled",
"java_version": "uninstalled",
"last_used": 1624457297
}],
"computer_sid": "",
"cpu_id": "",
"device_id": "",
"device_identifier": "3FA47335-1976-3BED-8286-D3F1ABCDEA13",
"device_identifier_type": "hardware_uuid",
"device_name": "ejmac",
"device_udid": "",
"device_username": "mba22915\u00e2\u0080\u0099s MacBook Air/mba22915",
"device_username_type": "os_username",
"disk_encryption_status": "On",
"domain_sid": "",
"email": "ejennings@example.com",
"epkey": "EP18JX1A10AB102M2T2X",
"firewall_status": "On",
"hardware_uuid": "3FA47335-1976-3BED-8286-D3F1ABCDEA13",
"health_app_client_version": "2.13.1.0",
"health_data_last_collected": 1624451421,
"last_updated": 1624451420,
"machine_guid": "",
"model": "",
"os_build": "19H1030",
"os_family": "Mac OS X",
"os_version": "10.11.7",
"password_status": "Set",
"security_agents": [{
"security_agent": "Cisco AMP for Endpoints",
"version": "10.1.2.3",
}],
"trusted_endpoint": "yes",
"type": "",
"username": "ejennings"
},
{
"browsers": [{
{
"browser_family": "Mobile Safari",
"browser_version": "9.0",
"flash_version": "uninstalled",
"java_version": "uninstalled"
}],
"computer_sid": "",
"cpu_id": "",
"device_id": "",
"device_identifier": "",
"device_identifier_type": "",
"device_name": "",
"device_udid": "",
"device_username": "",
"device_username_type": "",
"disk_encryption_status": "Unknown",
"domain_sid": "",
"email": "mhanson@example.com",
"epkey": "EP65MWZWXA10AB1027TQ",
"firewall_status": "Unknown",
"hardware_uuid": "",
"health_app_client_version": "",
"health_data_last_collected": "",
"last_updated": 1622036309,
"machine_guid": "",
"model": "iPhone",
"os_build": "",
"os_family": "iOS",
"os_version": "14.5.1",
"password_status": "Unknown",
"security_agents": [],
"trusted_endpoint": "unknown",
"type": "",
"username": "mhanson"
}],
}
Retrieve Endpoint by ID
Return information for an individual endpoint with epkey
. Requires "Grant resource - Read" API permission.
Some response information available for Duo Premier customers only.
GET /admin/v1/endpoints/[epkey]
Parameters
This API endpoint has no parameters.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
404 |
No endpoint was found with the given epkey .
|
Response Format
Same as Retrieve Endpoints.
Example Response
Example response for a Duo Advantage plan customer
{
"stat": "OK",
"response": {
"browsers": [{
"browser_family": "Edge Chromium",
"browser_version": "91.0.864.54",
"flash_version": "uninstalled",
"java_version": "uninstalled",
"last_used": 1624459875
}],
"computer_sid": "S-1-5-21-3284820969-3957662392-1842130629",
"cpu_id": "561699bcbac7533644465b4f16637adf5870773b571f6d5b90bbfaeb2f0ba568",
"device_identifier": "561699bcbac7533644465b4f16637adf5870773b571f6d5b90bbfaeb2f0ba568",
"device_identifier_type": "hardware_serial",
"device_name": "AMOSSPC",
"disk_encryption_status": "Off",
"domain_sid": "",
"email": "",
"epkey": "EPQC0C77F6MLXBCXCSWP",
"firewall_status": "On",
"hardware_uuid": "",
"health_app_client_version": "2.14.0",
"health_data_last_collected": 1624459875,
"last_updated": 1624459875,
"machine_guid": "6345e8c1-e717-4c68-a0f9-34cd0789e17f",
"model": "",
"os_build": "",
"os_family": "Windows",
"os_version": "10.0.19041.1052",
"password_status": "Set",
"type": "",
"username": "amoss"
},
}
Registered Devices
Retrieve Registered Devices
Returns a paged list of Duo Desktop registered devices. To fetch all results, call repeatedly with the offset
parameter as long as the result metadata has a next_offset
. If no number or extension parameters are provided, the list will contain all registered devices. Requires "Grant resource - Read" API permission.
GET /admin/v1/registered_devices
Parameters
Use the paging parameters to change the number of results shown in a response or to retrieve additional results. See Response Paging for details.
Paging Parameter | Required? | Description |
---|---|---|
limit
|
Optional |
The maximum number of records returned. Default: |
offset
|
Optional |
The offset from When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: |
This API endpoint has no additional parameters.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
Response Format
Key | Value |
---|---|
compkey
|
Computer/Device key. |
device_name
|
The endpoint's hostname. |
device_os
|
Operating system on the device. |
identifier
|
The unique device attribute value that identifies the endpoint. |
user
|
Selected information about the end user attached to this device. See Retrieve Users for descriptions of the response fields. |
Example Response
{
"metadata": {
"total_objects": 2
},
"response": [
{
"compkey": "CRSFWW1YWVNUXMBJ1J29",
"device_name": "CJONES-M-J1JF",
"device_os": "Mac OS X",
"identifier": "561699bcbac7533644465b4f16637adf5870773b571f6d5b90bbfaeb2f0ba568",
"user": [
{
"alias1": null,
"alias2": null,
"alias3": null,
"alias4": null,
"aliases": {},
"created": 1716491582,
"email": "cjones@example.com",
"enable_auto_prompt": true,
"firstname": "Chris",
"is_enrolled": true,
"last_directory_sync": null,
"last_login": 1716921006,
"lastname": "Jones",
"notes": "for CJ",
"realname": "Chris Jones",
"status": "active",
"user_id":"DUO3MIXQG78V9A0C29GS",
"username": "cjones"
},
{
"alias1": null,
"alias2": null,
"alias3": null,
"alias4": null,
"aliases": {},
"created": 1716562757,
"email": "cjones@example.com",
"enable_auto_prompt": true,
"firstname": "Chris",
"is_enrolled": true,
"last_directory_sync": null,
"last_login": 1716922823,
"lastname": "Jones",
"notes": "for CJ",
"realname": "Chris Jones",
"status": "active",
"user_id": "DULM95N4M4RVYO2HRYDW",
"username": "cjones"
}
]
},
{
"compkey": "CRSFWW1YWVNUXMBJ1J29",
"device_name": "CJONES-M-J1JF",
"device_os": "Mac OS X",
"identifier": "561699bcbac7533644465b4f16637adf5870773b571f6d5b90bbfaeb2f0ba568",
"user": [
{
"alias1": null,
"alias2": null,
"alias3": null,
"alias4": null,
"aliases": {},
"created": 1716562757,
"email": "cjones@example.com",
"enable_auto_prompt": true,
"firstname": "Chris",
"is_enrolled": true,
"last_directory_sync": null,
"last_login": 1716922823,
"lastname": "Jones",
"notes": "for CJ",
"realname": "Chris Jones",
"status": "active",
"user_id": "DULM95N4M4RVYO2HRYDW",
"username": "cjones"
}
]
}
],
"stat": "OK"}
Delete Registered Devices
Deletes a single registered device corresponding to the compkey
provided.
DELETE /admin/v1/registered_devices/[registered_device_key]
Parameters
This API endpoint has no parameters.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
404 |
No registered device was found with the given registered_device_key .
|
Response Format
Empty string.
Example Response
{
"stat": "OK",
"response": ""
}
Retrieve Registered Devices by ID
Return the single registered device with registered_device_key
. Requires "Grant resource - Read" API permission.
GET /admin/v1/registered_devices/[registered_device_key]
Parameters
This API endpoint has no parameters.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
404 |
No registered device was found with the given registered_device_key .
|
Response Format
Refer to Retrieve Registered Devices for an explanation of the object's keys.
Example Response
{
"response": {
"compkey": "CRSFWW1YWVNUXMBJ1J29",
"device_name": "CJONES-M-J1JF",
"device_os": "Mac OS X",
"identifier": "561699bcbac7533644465b4f16637adf5870773b571f6d5b90bbfaeb2f0ba568",
"user": [
{
"alias1": null,
"alias2": null,
"alias3": null,
"alias4": null,
"aliases": {},
"created": 1717178659,
"email": "cjones@example.com",
"enable_auto_prompt": true,
"firstname": "Chris",
"is_enrolled": true,
"last_directory_sync": null,
"last_login": 1717441468,
"lastname": "Jones",
"notes": "for CJ",
"realname": "Chris Jones",
"status": "active",
"user_id": "DUGE3VH8SOZP121FH3K6",
"username": "cjones"
}
]
},
"stat": "OK"
}
Passport
The Passport v2 API does not use the same authentication and request signing detailed earlier in this document. Our Python, Go, Java, and Node.JS API clients have been updated with the new authentication and signing requirements and include support for the Passport v2 API endpoint. We recommend you use the duo_client_python Python API client, the duo_api_golang Go API client, the duo_client_java Java API client, or the duo_api_nodejs Node.JS API client to interact with the Passport v2 endpoint.
Retrieve Passport Configuration
Returns the configuration for Duo Passport. Requires "Grant resource - Read" API permissions.
GET /admin/v2/passport/config
Parameters
This API endpoint has no parameters.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
Response Format
Key | Value | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
disabled_groups |
List of groups that have Passport disabled.
|
||||||||||
enabled_groups |
List of groups that have Passport enabled.
|
||||||||||
enabled_status |
The enabled status. One of:
|
Example Response
{
"response": {
"disabled_groups": [],
"enabled_groups": [
{
"group_id": "DAB12CDEFGHIJKLM3NOP",
"group_name": "Acme Group"
}
],
"enabled_status": "enabled-for-groups"
},
"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 - Read" or "Grant administrators - Write" and "Grant resource - Read" API permissions.
GET /admin/v1/admins
Parameters
Use the paging parameters to change the number of results shown in a response or to retrieve additional results. See Response Paging for details.
Paging Parameter | Required? | Description |
---|---|---|
limit
|
Optional |
The maximum number of records returned. Default: |
offset
|
Optional |
The offset from When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: |
This API endpoint has no additional parameters.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
Response Format
Key | Value | ||||||||
---|---|---|---|---|---|---|---|---|---|
admin_id
|
The administrator's ID. | ||||||||
admin_units
|
The list of administrative units (by admin_unit_id ) to which the admin belongs. For an unrestricted admin, this is an empty list.
|
||||||||
created
|
The administrator's creation date as a Unix timestamp. No creation date shown for administrators created before October 2021. |
||||||||
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_directory_sync
|
An integer indicating the last update to the administrator via directory sync as a Unix timestamp, or |
||||||||
last_login
|
An integer indicating 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 phone number in E.164 format. |
||||||||
restricted_by_admin_units
|
Is this administrator restricted by an administrative unit assignment? Either |
||||||||
role
|
The administrator's role. One of: "Owner", "Administrator", "Application Manager", "User Manager", "Security Analyst", "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. One of: "Active" (admin can log in to Duo), "Disabled" (admin prevented from access), "Expired" (admin blocked from access due to inactivity), or "Pending Activation" (new admin must complete activation to gain access). | ||||||||
webauthncredentials
|
A list of WebAuthn authenticators that this administrator can use.
|
Example Response
{
"stat": "OK",
"response": [
{
"admin_id": "DEVKWVBJA7LO95OIBIS3",
"admin_units": [],
"created": 1648143942,
"email": "rscott@example.com",
"hardtoken": {
"serial": "1234567890",
"token_id": "DH1TIP00LBCIH887OPSV",
"totp_step": null,
"type": "d1"
},
"last_directory_sync": null,
"last_login": 1343921403,
"name": "Rachael Scott",
"password_change_required": false,
"phone": "+17345551000",
"restricted_by_admin_units": false,
"role": "Owner",
"status": "Active",
"webauthncredentials": [
{
"credential_name": "Security key",
"date_added": 1679412977,
"webauthnkey": "WA1HOM2JP00L6HLP5JYM"
},
{
"credential_name": "Touch ID",
"date_added": 1679497182,
"webauthnkey": "WABNYB93OD4DVWVBC41X"
}
]
},
{
"admin_id": "DEVKWVBJA7P00LD4DIS3",
"admin_units": [],
"created": 1648146942,
"email": "fulan@example.com",
"hardtoken": {},
"last_directory_sync": 1658850983,
"last_login": 1343971403,
"name": "Fulan Al Fulani",
"password_change_required": false,
"phone": "+17345551100",
"restricted_by_admin_units": false,
"role": "Administrator",
"status": "Active"
}
]
}
Create Administrator
Create a new administrator. Requires "Grant administrators - Write" 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; E.164 format recommended (i.e. "+17345551212"). If no leading plus sign is provided then it is assumed to be a United States number and an implicit "+1" country code is prepended. Dashes and spaces are ignored. If this parameter is specified it cannot be empty. |
role
|
Optional |
The administrator's role. One of: "Owner", "Administrator", "Application Manager", "User Manager", "Security Analyst", "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 |
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:: 31
|
Response Codes
Response | Meaning |
---|---|
200 | Success. Returns the newly created administrator. |
400 | Invalid or missing parameters, the role assigned may not be restricted by an administrative unit, or the provided email address is already in use by another administrator. |
Response Format
Returns the created single administrator object, with the same information as Retrieve Administrator by ID plus:
activation_url_expires
|
An integer indicating the 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",
"admin_units": [],
"created": 1648143942,
"email": "rscott@example.com",
"hardtoken": null,
"last_directory_sync": 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 admin_id
. Requires "Grant administrators - Read" or "Grant administrators - Write" API permission.
GET /admin/v1/admins/[admin_id]
Parameters
This API endpoint has no parameters.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
404 |
No administrator was found with the given admin_id .
|
Response Format
Returns the single administrator object, with the same information as Retrieve Administrators plus:
activation_url
|
Link to the activation form if an activation link exists for that admin. |
Example Response
{
"stat": "OK",
"response": {
"admin_id": "DEA0HJ95P00LNFXO9DEMK",
"admin_units": [],
"created": null,
"email": "ellery.munson@example.com",
"hardtoken": {
"serial": "100048",
"token_id": "DH89J6KJAF00BQ2ILS0K",
"totp_step": null,
"type": "h6"
},
"last_directory_sync": null,
"last_login": 1679517329,
"name": "Ellery Munson",
"password_change_required": false,
"phone": "+17345559542",
"restricted_by_admin_units": false,
"role": "Administrator",
"status": "Active",
"webauthncredentials": [
{
"credential_name": "Touch ID",
"date_added": 1679517297,
"webauthnkey": "WAJ3YT0D4DMSIW9F6MVC"
}
]
}
}
Modify Administrator
Change the name, phone number, or other properties of the administrator with the administrator ID admin_id
. Requires "Grant administrators - Write" API permission.
POST /admin/v1/admins/[admin_id]
Parameters
Parameter | Required? | Description |
---|---|---|
name
|
Optional | New name for the administrator. Read-only if the admin is managed by directory sync. |
phone
|
Optional |
The phone number; E.164 format recommended (i.e. "+17345551212"). If no leading plus sign is provided then it is assumed to be a United States number and an implicit "+1" country code is prepended. Dashes and spaces are ignored. 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. May not be changed to true if the admin has external password management enabled.
|
role
|
Optional |
New role for the administrator. One of: "Owner", "Administrator", "Application Manager", "User Manager", "Security Analyst", "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. Read-only if the admin is managed by directory sync. |
restricted_by_admin_units
|
Optional |
Is this administrator restricted by an administrative unit assignment? Either |
status
|
Optional | The desired administrator account status. Either "Active" or "Disabled" (case-sensitive). Administrators with the "Owner" role may not be disabled via API. To clear an inactive admin's "Expired" status, see Clear Administrator Expiration. Read-only if the admin is managed by directory sync. |
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, or the role assigned may not be restricted by an administrative unit. |
404 |
No administrator was found with the given admin_id .
|
Response Format
Returns the single modified administrator object. Refer to Retrieve Administrators for an explanation of the object's keys.
Example Response
Same as Retrieve Administrator by ID.
Delete Administrator
Delete the administrator with administrator ID admin_id
from the system. Administrators managed by directory sync can not be deleted via API. Requires "Grant administrators - Write" API permission.
DELETE /admin/v1/admins/[admin_id]
Parameters
This API endpoint has no parameters.
Response Codes
Response | Meaning |
---|---|
200 | The administrator was deleted or did not exist. |
400 | The administrator could not be deleted. |
Response Format
Empty string.
Example Response
{
"stat": "OK",
"response": ""
}
Reset Administrator Authentication Attempts
Clear the number of failed login attempts for the administrator with admin_id
. Re-enables an administrator who has been disabled due to too many failed authentication attempts. Requires "Grant administrators - Write" API permission.
POST /admin/v1/admins/[admin_id]/reset
Parameters
This API endpoint has no parameters.
Response Codes
Response | Meaning |
---|---|
200 | The administrator's authentication failure count was set to zero. |
404 |
No administrator was found with the given admin_id .
|
Response Format
Empty string.
Example Response
{
"stat": "OK",
"response": ""
}
Clear Administrator Expiration
Clear expiration for the administrator with admin_id
after the admin has been expired due to inactivity. The administrator's status changes from "Expired" to the status applied to that admin before inactive expiration, and restores access to the Duo Admin Panel if the effective status is "Active". Requires "Grant administrators - Write" API permission.
POST /admin/v1/admins/[admin_id]/clear_inactivity
Parameters
This API endpoint has no parameters.
Response Codes
Response | Meaning |
---|---|
200 | The administrator's "Expired" status was cleared. |
404 |
No administrator was found with the given admin_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 admin_id
. Requires "Grant administrators - Write" API permission.
POST /admin/v1/admins/[admin_id]/activation_link/email
Parameters
This API endpoint has no parameters.
Response Codes
Response | Meaning |
---|---|
200 | An email with the activation link was sent to the admin. |
400 | Invalid administrator for activation. |
404 |
Invalid admin_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
|
An integer indicating the 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 admin_id
. Requires "Grant administrators - Write" API permission.
DELETE /admin/v1/admins/[admin_id]/activation_link
Parameters
This API endpoint has no parameters.
Response Codes
Response | Meaning |
---|---|
200 | Any existing activation link was deleted and invalidated. |
400 | Invalid administrator for activation. |
404 |
Invalid admin_id .
|
Response Format
Same as Retrieve Administrator by ID.
Example Response
{
"stat": "OK",
"response": {
"admin_id": "DEVKWVBJA7LO95OIBIS3",
"admin_units": [],
"created": 1648143942,
"email": "rscott@example.com",
"hardtoken": null,
"last_directory_sync": 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 admin_id
. There must not already be an existing activation link for the admin. Requires "Grant administrators - Write" API permission.
POST /admin/v1/admins/[admin_id]/activation_link
Parameters
This API endpoint has no parameters.
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 admin_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",
"admin_units": [],
"created": 1648143942,
"email": "rscott@example.com",
"hardtoken": null,
"last_directory_sync": 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 - Write" 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","Security Analyst", "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: 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
|
An integer indicating the Unix timestamp of the activation link's expiration. |
link
|
Link to the activation form. |
message
|
Introductory message body. |
subject
|
Introductory message subject. |
valid_days
|
An integer indicating the number of days before the activation link expires. |
Example Response
{
"stat": "OK",
"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
},
}
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 - Read" or "Grant administrators - Write" API permission.
GET /admin/v1/admins/activations
Parameters
Use the paging parameters to change the number of results shown in a response or to retrieve additional results. See Response Paging for details.
Paging Parameter | Required? | Description |
---|---|---|
limit
|
Optional |
The maximum number of records returned. Default: |
offset
|
Optional |
The offset from When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: |
This API endpoint has no additional parameters.
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
|
An integer indicating the timestamp of the activation link's expiration. |
Example Response
{
"stat": "OK",
"response": {
"admin_activation_id": "DK9PHLB5Z8NZJRFSJX4Q",
"code": "g793cfba2b4e8684164c6b8766baad08",
"email": "sogilby@example.com",
"expires": 1550075404
},
}
Delete Pending Administrator Activation
Delete the pending admin activation with ID admin_activation_id
from the system. Requires "Grant administrators - Write" API permission.
DELETE /admin/v1/admins/activations/[admin_activation_id]
Parameters
This API endpoint has no parameters.
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": ""
}
Synchronize Admin from Directory
Initiate a sync to create, update, or mark for deletion the administrator specified by email
against the directory specified by the directory_key
. The directory_key
for a directory can be found by navigating to Administrators → Admin Directory Sync in the Duo Admin Panel, and then clicking on the configured directory. Learn more about syncing individual admins from Active Directory, OpenLDAP, or Entra ID. Requires "Grant administrators - Write" API permission.
POST /admin/v1/admins/directorysync/[directory_key]/syncadmin
Parameters
Parameter | Required? | Description |
---|---|---|
email
|
Required | Email address of the admin to update or create via directory sync. This should be the same as the value for the admin's email attribute in the source directory as configured in the sync. Administrators with "Owner" role may not be synced. |
Response Codes
Response | Meaning |
---|---|
200 | The admin was synced successfully and updated or added in Duo. The admin object is also returned (see Retrieve Users). |
404 |
The specified email or directory_key was incorrect, the admin is not managed by the specified directory, or the admin is not a member of any source directory group specified in the sync configuration.
|
429 | Too many requests; try again later. |
Response Format
Returns the single synced administrator object with an additional message
stating the admin synced successfully. Refer to Retrieve Administrators for an explanation of the object's keys.
Example Response
{
"stat": "OK",
"response":{
"admin": {
"admin_id": "DE98U1VAFZ6CO4T06HZO",
"admin_units": [],
"created": 1658850929,
"email": "sogilby@example.com",
"hardtoken": null,
"last_directory_sync": 1658850983,
"last_login": null,
"name": "Soren Ogilby",
"password_change_required": false,
"phone": "+17345559777",
"restricted_by_admin_units": false,
"role": "Help Desk",
"status": "Pending Activation"
},
"message": "User sogilby@example.com synced successfully."
}
Retrieve Admin External Password Management Status
Returns a paged list of administrators indicating whether they have been configured for external password management. To fetch all results, call repeatedly with the offset
parameter as long as the result metadata has a next_offset
value. Requires "Grant administrators - Read" or "Grant administrators - Write" API permission.
GET /admin/v1/admins/password_mgmt
Parameters
Use the paging parameters to change the number of results shown in a response or to retrieve additional results. See Response Paging for details.
Paging Parameter | Required? | Description |
---|---|---|
limit
|
Optional |
The maximum number of records returned. Default: |
offset
|
Optional |
The offset from When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: |
This API endpoint has no additional parameters.
Response Codes
Response | Meaning |
---|---|
200 | Returns a list of administrators with each admin's external password management status. |
400 | Invalid paging parameters. |
Response Format
Key | Value |
---|---|
admin_id
|
The administrator's ID. |
email
|
The administrator's email address. |
has_external_password_mgmt
|
Either true if the administrator's password may be set via API, or false if passwords are self-managed (default).
|
Example Response
{
"stat": "OK",
"response": [
{
"admin_id": "DEORP00LUIXPGD4DCC37",
"email": "sogilby@example.com",
"has_external_password_mgmt": false
},
],
}
Retrieve Admin External Password Management Status by ID
Returns the external password management configuration for the single administrator with the administrator ID admin_id
. Requires "Grant administrators - Read" or "Grant administrators - Write" API permission.
GET /admin/v1/admins/[admin_id]/password_mgmt
Parameters
This API endpoint has no parameters.
Response Codes
Response | Meaning |
---|---|
200 | Returns the specified administrator's password management status. |
404 |
No administrator was found with the given admin_id .
|
Response Format
Same as Retrieve Admin External Password Management Status.
Example Response
{
"stat": "OK",
"response": {
"admin_id": "DEORP00LUIXPGD4DCC37",
"email": "sogilby@example.com",
"has_external_password_mgmt": false
},
}
Modify Admin External Password Management Status or Password
Enable or disable an administrator, specified by admin_id
, for external password management, or set the password for an administrator with has_external_password_mgmt
set to true
(either passed in with the same POST or previously set).
Administrator passwords must have at least twelve characters, and may also require a mix of character types depending on your Admin Password Policy settings. New passwords will be checked against common passwords, usernames, and other account information to ensure uniqueness.
Setting has_external_password_mgmt
also updates the administrator account's password_change_required
value. When has_external_password_mgmt
is set to true
, password_change_required
is updated to false
, as enabling external password management restricts administrators from performing self-service password resets via the Duo Admin Panel UI. When has_external_password_mgmt
is set to false
, password_change_required
is updated to true
to ensure that an administrator no longer subject to external password management updates their password to a new value not known by the external system.
POST /admin/v1/admins/[admin_id]/password_mgmt
Parameters
Parameter | Required? | Description |
---|---|---|
has_external_password_mgmt
|
Optional |
Specify true if the administrator's password may be set via API, or false if passwords are self-managed. If specifying true you may also send a password value in the same operation.
|
password
|
Optional |
New password for the administrator. May be sent in the same operation with has_external_password_mgmt=true
|
Response Codes
Response | Meaning |
---|---|
200 | Success. |
400 | Password specified when external password management not enabled for the admin, or new password does not satisfy the password policy. |
404 |
No administrator was found with the given admin_id .
|
Response Format
Key | Value |
---|---|
admin_id
|
The administrator's ID. |
email
|
The administrator's email address. |
has_external_password_mgmt
|
Returns true if the administrator's password may be set via API, or false if passwords are self-managed. If the setting was changed in the request then the new value is returned.
|
password_changed
|
Returns true if the administrator's password was changed in the request, or false if the request did not attempt to change the password.
|
Example Response
{
"stat": "OK",
"response": {
"admin_id": "DEORP00LUIXPGD4DCC37",
"email": "sogilby@example.com",
"has_external_password_mgmt": true,
"password_changed": true
},
}
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 - Read" or "Grant administrators - Write" API permission.
GET /admin/v1/admins/allowed_auth_methods
Parameters
This API endpoint has no parameters.
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.
|
webauthn_enabled
|
If true , administrators may authenticate to the Duo Admin Panel with a WebAuthn credential (also known as a passkey). If false , administrators may not use passkeys.
|
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,
"webauthn_enabled": true,
"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 - Write" 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.
|
webauthn_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 WebAuthn credential (also known as a passkey). If false or not specified, administrators may not use passkeys.
|
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 - Read" or "Grant administrators - Write" 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
Use the paging parameters to change the number of results shown in a response or to retrieve additional results. See Response Paging for details.
Paging Parameter | Required? | Description |
---|---|---|
limit
|
Optional |
The maximum number of records returned. Default: |
offset
|
Optional |
The offset from When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: |
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. |
description
|
The administrative unit's description. |
name
|
The administrative unit's name. |
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 - Read" or "Grant administrators - Write" API permission.
GET /admin/v1/administrative_units/[admin_unit_id]
Parameters
This API endpoint has no parameters.
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. |
admins
|
The administrators assigned to the new administrative unit, listed by admin_id .
|
description
|
The administrative unit's description. |
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 .
|
name
|
The administrative unit's name. |
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": "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 - Write" 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: |
restrict_by_integrations
|
Optional |
Does the new administrative unit specify integrations?
Default: |
admins
|
Optional |
One or more |
groups
|
Optional |
One or more |
integrations
|
Optional |
One or more |
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 - Write" 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 |
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 - Write" API permission.
POST /admin/v1/administrative_units/[admin_unit_id]/admin/[admin_id]
Parameters
This API endpoint has no parameters.
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 - Write" API permission.
DELETE /admin/v1/administrative_units/[admin_unit_id]/admin/[admin_id]
Parameters
This API endpoint has no parameters.
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 - Write" API permission.
POST /admin/v1/administrative_units/[admin_unit_id]/group/[group_id]
Parameters
This API endpoint has no parameters.
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 - Write" API permission.
DELETE /admin/v1/administrative_units/[admin_unit_id]/group/[group_id]
Parameters
This API endpoint has no parameters.
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 - Write" API permission.
POST /admin/v1/administrative_units/[admin_unit_id]/integration/[integration_key]
Parameters
This API endpoint has no parameters.
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 integration_key
from the administrative unit with admin_unit_id
. Requires "Grant administrators - Write" API permission.
DELETE /admin/v1/administrative_units/[admin_unit_id]/integration/[integration_key]
Parameters
This API endpoint has no parameters.
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 - Write" API permission.
DELETE /admin/v1/administrative_units/[admin_unit_id]
Parameters
This API endpoint has no parameters.
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
Use the paging parameters to change the number of results shown in a response or to retrieve additional results. See Response Paging for details.
Paging Parameter | Required? | Allow Multiple? | Description | ||||||
---|---|---|---|---|---|---|---|---|---|
limit
|
Optional | No |
The maximum number of records returned. Default: |
||||||
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 When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: None Example: |
||||||
sort
|
Optional | No |
The order in which to return records. One of:
|
Parameter | Required? | Allow Multiple? | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
mintime
|
Required | No |
Return records that have a 13 character Unix Example: |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
maxtime
|
Required | No |
Return records that have a 13 character Unix Example: |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
applications
|
Optional |
Yes. Multiple values create an OR query.
|
An integration's Default: Return logs for all applications. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
users
|
Optional |
Yes. Multiple values create an OR query.
|
A user's Default: Return logs for all users. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
assessment
|
Optional |
Yes. Multiple values create an OR query.
|
The risk-based authentication assessment based on risk-based factor selection (RBFS) and risk-based remembered device (RBRD) policy enforcement. This information is available to Duo Premier and Duo Advantage plan customers. One of:
Default: Return logs for all assessments. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
detections |
Optional | Yes. Multiple values create an OR query. |
The risk-based authentication detections found during or after an authentication attempt. This information is available to Duo Premier and Duo Advantage plan customers. One of: "consecutive failures", "country code mismatch", "credential stuffing", "device distance", "expired cookie", "manual removal by the user", "novel asn", "novel ip and wifi fingerprint", "policy change", "previously marked fraud", "push harassment", "service outage detected", "session not found", "tampered cookie", or "unrealistic travel". Default: Return logs for all detections. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
event_types
|
Optional |
Yes. Multiple values create an OR query.
|
The type of authentication event. One of:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
factors |
Optional | Yes. Multiple values create an OR query. |
The factor or method used for an authentication attempt. One of:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
formatter |
Optional | No |
|
Specifies the log format. If omitted, logs are returned in the default format. One of:
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
groups
|
Optional |
Yes. Multiple values create an OR query.
|
A group's Default: Return logs for all groups. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
phone_numbers
|
Optional |
Yes. Multiple values create an OR query.
|
A phone's 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:
Default: Return logs for any result. Filtering on all values is equivalent to the default. Note that enrollment events have no associated |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
results
|
Optional |
Yes. Multiple values create an OR query.
|
The result of an authentication attempt. One of:
Default: Return logs for any result. Filtering on all values is equivalent to the default. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
tokens
|
Optional |
Yes. Multiple values create an OR query.
|
A WebAuthn security key's 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 Premier and Duo Advantage plan customers.
|
||||||||||||||||||||||||||||||||||
adaptive_trust_assessments
|
Risk-based authentication information. Values present only when the application accessed features Duo's inline browser prompt and has a Duo Risk-Based Authentication policy applied. This information is available to Duo Premier and Duo Advantage plan customers. Type of adaptive trust assessment. One of:
|
||||||||||||||||||||||||||||||||||
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.
|
||||||||||||||||||||||||||||||||||
auth_device
|
Information about the device used to approve or deny authentication.
|
||||||||||||||||||||||||||||||||||
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: "bypass_code", "Desktop Authenticator", "digipass_go_7_token", "duo_mobile_passcode", "duo_mobile_passcode_hotp", "duo_mobile_passcode_totp", "duo_push", "hardware_token", "not_available", "passcode", "phone_call", "Platform authenticator (2fa)", "remembered_device", "Roaming authenticator (2fa)", "sms_passcode", "sms_refresh", "trusted_mobile_authenticator", "trusted_network" "u2f_token", "verified_duo_push", "WebAuthn Chrome Touch ID", "WebAuthn Credential", "WebAuthn Security Key", or "yubikey_passcode". |
||||||||||||||||||||||||||||||||||
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. |
||||||||||||||||||||||||||||||||||
passport_assessment
|
Information on whether the authentication supported Duo Passport. Will return for all authentications, even if Duo Passport is not enabled. Authentication logs before August 2024 will not return this field.
|
||||||||||||||||||||||||||||||||||
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", "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", "frequent_attempts", "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". Note that enrollment events have no associated |
||||||||||||||||||||||||||||||||||
result
|
The result of the authentication attempt. One of: "success", "denied", "failure", "error", or "fraud". | ||||||||||||||||||||||||||||||||||
timestamp
|
An integer indicating the Unix timestamp of the event. | ||||||||||||||||||||||||||||||||||
txid
|
The transaction ID of the event. | ||||||||||||||||||||||||||||||||||
user
|
Information about the authenticating user.
|
Example Response
200 OK
{
"stat": "OK",
"response": {
"authlogs": [
{
"access_device": {
"browser": "Chrome",
"browser_version": "67.0.3396.99",
"epkey": "EP18JX1A10AB102M2T2X",
"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": []
},
"adaptive_trust_assessments": {
"more_secure_auth": {
"detected_attack_detectors": [
"USER_MARKED_FRAUD"
],
"features_version": "3.0",
"model_version": "2022.07.19.001",
"policy_enabled": true,
"reason": "Low level of trust; detection of one or more known attack patterns",
"trust_level": "LOW"
},
"remember_me": {
"features_version": "3.0",
"model_version": "2022.07.19.001",
"policy_enabled": false,
"reason": "Known Access IP",
"trust_level": "NORMAL"
}
},
"alias": "",
"application": {
"key": "DIY231J8BR23QK4UKBY8",
"name": "Microsoft Azure Active Directory"
},
"auth_device": {
"ip": "192.168.225.254",
"key": "DP5BJ05HI4WRBVI4Q7JF",
"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,
"passport_assessment": {
"is_supported": false,
"reason": "absent_health_report"
},
"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
}
},
}
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 |
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 Premier and Duo Advantage plan customers.
|
||||||||||||||
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 Desktop", "Duo Mobile Inline Auth", "Duo Mobile Passcode", "Duo Mobile Passcode (HOTP)", "Duo Mobile Passcode (TOTP)", "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.
|
||||||||||||||
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", "Call timed out", "Couldn't determine if endpoint was trusted", "Denied by policy", "Deny unenrolled user", "Duo Mobile version restricted", "Endpoint is not in Management System", "Factor restricted", "Frequent attempts", "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", or "User provided an invalid certificate". If result is "ERROR" then: "Error". If result is "FRAUD" then: "User marked fraud". Note that enrollment events have no associated |
||||||||||||||
result
|
The result of the authentication attempt. One of: "success", "denied", "failure", "error", or "fraud". | ||||||||||||||
timestamp
|
An integer indicating the 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",
"location": {
'city': 'Ann Arbor',
'state': 'Michigan',
'country': 'US'
},
"new_enrollment": false,
"ood_software": "",
"reason": "User approved",
"result": "SUCCESS",
"timestamp": 1581620180,
"username": "jsmith",
}]
}
Activity Logs
Returns a paged list of activity log events ranging from the last 180 days up to as recently as two minutes before the API request. The events returned are subject to log retention, if set up in the account, as described here. 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 the availability of new activity events 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.
GET /admin/v2/logs/activity
Parameters
Query Parameter | Required? | Allow Multiple? | Description | ||||||
---|---|---|---|---|---|---|---|---|---|
mintime |
Required | No |
Return records that have a 13 character Unix Example: |
||||||
maxtime |
Required | No |
Return records that have a 13 character Unix Maximum: 180 days Example: |
||||||
limit |
Optional | No |
The maximum number of records returned. Default: |
||||||
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 When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: None Example: |
||||||
sort |
Optional | No |
The order in which to return records. One of:
Default: |
Response Codes
Response | Meaning |
---|---|
200 | Success. |
400 | Invalid or missing parameters or mintime is after the maxtime . |
Response Format
Key | Value | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
items |
List of activity logs. Information included:
|
Example Response
{
"response": {
"items": [
{
"access_device": {
"browser": "Chrome",
"browser_version": "111.0.0.0",
"epkey": "EP123456789012345678",
"ip": {
"address": "172.34.40.116"
},
"location": {
"city": "Ann Arbor",
"country": "United States",
"state": "Michigan"
},
"os": "Mac OS X",
"os_version": "10.15.7"
},
"action": {
"details": null,
"name": "webauthncredential_create"
},
"activity_id": "720b8360-078b-47c4-adc7-7968df1caef0",
"actor": {
"details": "{\"created\": \"2015-09-25T23:17:40.000000+00:00\", \"last_login\":
\"2023-03-21T19:51:09.000000+00:00\", \"status\": \"Active\", \"groups\": [{\"name\":
\"CorpHQ_Users\", \"key\": \"DGAZ172QBWDM26AK8ITK\"}, {\"name\": \"ITAdmins\", \"key\":
\"DGK3B7XTSIP00LKHK1RD\"}, {\"name\": \"yee\", \"key\": \"DGKZWSBCDADEVFGFK5NR\"}]}",
"key": "DU64TKJPJ0SHFWKO2LNBC",
"name": "sogilby",
"type": "user"
},
"akey": "DAAR5FO0OZ4VYZA0WOB2",
"application": {
"key": "DILSVDEYH66TBHKIXGR9",
"name": "Acme Corp",
"type": "websdk"
},
"old_target": null,
"outcome": {
"result"; "FAILURE"
}
"target": {
"details": "{\"authenticator_type\": \"Security key\", \"transport_types\": \"usb\",
\"passwordless_authorized\": false, \"browser\": \"Chrome\", \"browser_version\":
\"111.0.0.0\", \"os\": \"Mac OS X\", \"os_version\": \"10.15.7\", \"user_agent\":
\"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko)
Chrome/111.0.0.0 Safari/537.36\", \"credential_name\": \"Security key\"}",
"key": "WAUKH0IMTGP00L90LT4KM",
"name": "WAUKH0IMTG3EDD4DT4KM",
"type": "webauthn_credential"
},
"ts": "2023-03-21T15:51:22.591015+00:00"
}
],
"metadata": {
"next_offset": "1666714065304,5bf1a860-fe39-49e3-be29-217659663a74",
"total_objects": 1
}
},
"stat": "OK",
}
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 in seconds 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:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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 Duo 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 |
An integer indicating the 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 paged list of telephony log events ranging from the last 180 days up to as recently as two minutes before the API request. The events returned are subject to log retention, if set up in the account, as described here. 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 the availability of new telephony events 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.
The v2 handler provides new querying capabilities and contextual information for events unavailable in the legacy v1 handler.
We recommend requesting logs no more than once per minute.
GET /admin/v2/logs/telephony
Parameters
Query Parameter | Required? | Allow Multiple? | Description | ||||||
---|---|---|---|---|---|---|---|---|---|
mintime
|
Required | No |
Return records that have a 13 character Unix Example: |
||||||
maxtime
|
Required | No |
Return records that have a 13 character Unix Maximum: 180 days Example: |
||||||
limit
|
Optional | No |
The maximum number of records returned. Default: |
||||||
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 When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: None Example: |
||||||
sort
|
Optional | No |
The order in which to return records. One of:
Default: |
Response Codes
Response | Meaning |
---|---|
200 | Success. |
400 |
Invalid or missing parameters or mintime is after the maxtime .
|
Response Format
Key | Value | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
items
|
List of telephony logs. Information included:
|
Example Response
{
"stat": "OK",
"response": {
"items": [
{
"context": "enrollment",
"credits": 1,
"phone": "+12125556707",
"telephony_id": "220f89ff-bff8-4466-b6cb-b7787940ce68",
"ts": "2023-03-21T22:34:49.466370+00:00",
"txid": "2f5d34d3-053f-422c-9dd4-77a5d58706b1",
"type": "sms"
},
{
"context": "authentication",
"credits": 2,
"phone": "+17345551311",
"telephony_id": "60799fee-f08f-4ba8-971f-4e53b3473e9a",
"ts": "2023-01-26T20:54:12.573580+00:00",
"txid": "373bd5f3-1e42-4a5d-aefa-b33ae278fac8",
"type": "phone"
},
{
"context": "administrator login",
"credits": 0,
"phone": "+13135559542",
"telephony_id": "5bf1a860-fe39-49e3-be29-217659663a74",
"ts": "2022-10-25T16:07:45.304526+00:00",
"txid": "fb0c129b-f994-4d3d-953b-c3e764272eb7",
"type": "sms"
}
],
"metadata": {
"next_offset": "1666714065304,5bf1a860-fe39-49e3-be29-217659663a74",
"total_objects": 3
}
}
}
Telephony Logs (Legacy v1)
The v2 telephony logs endpoint provides new querying capabilities and contextual information for events unavailable in the legacy v1 handler. Consider migrating to the new handler.
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 in seconds after mintime . This can help to avoid fetching records that have already been retrieved.
|
Response Codes
Response | Meaning |
---|---|
200 | Success. |
Response Format
Key | Value |
---|---|
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. |
timestamp
|
An integer indicating the Unix timestamp of the 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 |
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.
|
||||||
isotimestamp
|
ISO8601 timestamp of the event. |
||||||
object
|
The Duo Windows Logon integration's name .
|
||||||
timestamp
|
An integer indicating the 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
This information is available to Duo Premier and Duo Advantage plan customers.
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
Parameters
Use the paging parameters to change the number of results shown in a response or to retrieve additional results. See Response Paging for details.
Paging Parameter | Required? | Description |
---|---|---|
limit
|
Optional |
The maximum number of records returned. Default: |
offset
|
Optional |
The offset from When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: |
Parameter | Required? | Description | ||||||||
---|---|---|---|---|---|---|---|---|---|---|
mintime
|
Required |
Return records that have a 13 character Unix |
||||||||
maxtime
|
Required |
Return records that have a 13 character Unix |
||||||||
formatter |
Optional |
|
Specifies the log format. If omitted, logs are returned in the default format. One of:
||||||||
type
|
Optional |
The type of security event.
|
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 Parameters. The information returned for each event includes:
|
Example Response
Authentication Event:
{
"stat": "OK",
"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",
"epkey": "EP18JX1A10AB102M2T2X",
"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,
"key": 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"
}
},
}
Bypass Status Enabled Event:
{
"stat": "OK",
"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": {}
},
}
Device Registration Event:
{
"stat": "OK",
"response": {
"events": [
{
"explanations": [
{
"summary": "The registered device has an out-of-date version of the operating system installed.",
"type": "REGISTER_OS_OUTDATED"
}
],
"from_new_user": false,
"priority_event": false,
"priority_reasons": [],
"sekey": "SEDOR9BP00L23C6YUH7",
"state": "new",
"state_updated_timestamp": null,
"surfaced_timestamp": 1675893605269,
"triaged_as_interesting": false,
"type": "device_registration"
}
],
"metadata": {}
},
}
Settings
Retrieve Settings
Returns global Duo settings. These settings can also be viewed and set in the Duo Admin Panel. Requires "Grant settings" API permission.
GET /admin/v1/settings
Parameters
This API endpoint has no parameters.
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. | ||||||||||
duo_mobile_otp_type
|
The one-time passcode setting for Duo Mobile. One of:
|
||||||||||
email_activity_notification_enabled
|
If true , users will receive an email notification when an authentication device is added or removed. If set to false , no email notifications are sent in these situations.
|
||||||||||
enrollment_universal_prompt_enabled
|
If true , the enrollment experience will show the Universal Prompt. If false , the enrollment experience will show the traditional Duo Prompt.
|
||||||||||
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.
|
||||||||||
global_ssp_policy_enforced
|
If true , a policy set by an administrator is enforced for users trying to access the self-service portal. If set to false , the policy to access the self-service portal will be determined by the destination application policy.
|
||||||||||
helpdesk_bypass
|
Grants permission for administrators with the Help Desk role to generate bypass codes for users. One of allow (default value), limit , or deny .
|
||||||||||
helpdesk_bypass_expiration
|
Integer specifying a default expiration for bypass codes generated by Help Desk admins, in minutes. If not set, Help Desk admins may change bypass code expiration from the default 60 minutes after creation if helpdesk_bypass is set to allow .
|
||||||||||
helpdesk_can_send_enroll_email
|
Permits Help Desk administrators to send or resend enrollment emails to users. One of true or false (default).
|
||||||||||
helpdesk_message
|
Legacy parameter; no effect if specified. Use the Retrieve Custom Messaging endpoint. | ||||||||||
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 traditional Duo browser-based user authentication prompt. One of: "EN", "DE", "FR". Default: "EN" | ||||||||||
lockout_expire_duration
|
If non-zero, an integer indicating 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. | ||||||||||
log_retention_days
|
When set, log entries older than the specified number of days are purged. Logs retained indefinitely if null . Note that the log retention setting does not change the 180 day limitation for viewing and retrieving log information in the Duo Admin Panel, exported reports, or via this API.
Minimum: 1 day.
Maximum: 365 days.
|
||||||||||
minimum_password_length
|
An integer indicating 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
|
Legacy parameter; no effect if specified and always returns |
||||||||||
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_activity_notification_enabled
|
If true , users will receive a Duo Mobile notification when an authentication device is added or removed. If set to false , no email notifications are sent in these situations.
|
||||||||||
push_enabled
|
Legacy parameter; no effect if specified and always returns |
||||||||||
sms_batch
|
An integer that indicates how many passcodes to send at one time, up to 10. | ||||||||||
sms_enabled
|
Legacy parameter; no effect if specified and always returns |
||||||||||
sms_expiration
|
The time in minutes to expire and invalidate SMS passcodes, up to 16,777,215. | ||||||||||
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
|
An integer indicating 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 Duo Admin Panel. | ||||||||||
unenrolled_user_lockout_threshold
|
If non-zero, this is the number of days users can be unenrolled for before they are put into a locked out status. If 0 , then users will not be put into a locked out status if they are unenrolled for any given period of time. Default value is 0 .
|
||||||||||
user_managers_can_put_users_in_bypass
|
Permits User Manager administrators to apply "Bypass" status to users. One of true (default) or false .
|
||||||||||
user_telephony_cost_max
|
An integer indicating 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 .
|
||||||||||
voice_enabled
|
Legacy parameter; no effect if specified and always returns |
Example Response
{
"stat": "OK",
"response": {
"caller_id": "+15035551000",
"duo_mobile_otp_type": "TOTP and HOTP",
"email_activity_notification_enabled": false,
"enrollment_universal_prompt_enabled": true,
"fraud_email": "example@example.com",
"fraud_email_enabled": true,
"global_ssp_policy_enforced": true;
"helpdesk_bypass": "allow",
"helpdesk_bypass_expiration": 0,
"helpdesk_can_send_enroll_email": false,
"helpdesk_message": "",
"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": false,
"name": "Acme Corp",
"password_requires_lower_alpha": true,
"password_requires_numeric": true,
"password_requires_special": false,
"password_requires_upper_alpha": true,
"push_enabled": false,
"req_fips_passcodes_android": false,
"security_checkup_enabled": 1,
"sms_batch": 1,
"sms_enabled": false,
"sms_expiration": 10,
"sms_message": "SMS passcodes",
"sms_refresh": 0,
"telephony_warning_min": 0,
"timezone": "UTC",
"user_managers_can_put_users_in_bypass": true,
"user_telephony_cost_max": 20.0,
"voice_enabled": false,
}
}
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. Customizing this number may cause telephony providers to flag your number as fraudulent and result in failed user authentications. | ||||||||||
duo_mobile_otp_type
|
Optional |
The one-time passcode setting for Duo Mobile. One of:
|
||||||||||
email_activity_notification_enabled
|
Optional |
If true , users will receive an email notification when an authentication device is added or removed. If set to false , no email notifications are sent in these situations. Default value is false .
|
||||||||||
enrollment_universal_prompt_enabled
|
Optional |
If true , the enrollment experience will show the Universal Prompt. If false , the enrollment experience will show the traditional Duo Prompt. Default: show the Universal Prompt (for new customers as of July 2022).
|
||||||||||
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.
|
||||||||||
global_ssp_policy_enforced
|
Optional |
If true , a policy set by an administrator is enforced for users trying to access the self-service portal. If set to false , the policy to access the self-service portal will be determined by the destination application policy. Default value is true .
|
||||||||||
helpdesk_bypass
|
Optional |
Grants permission for administrators with the Help Desk role to generate bypass codes for users. The default value allow permits unrestricted generation of bypass codes, limit plus a value for helpdesk_bypass_expiration allows Help Desk admins to generate bypass codes with a preset expirtation, and deny prevents Help Desk admins from generating any bypass codes.
|
||||||||||
helpdesk_bypass_expiration
|
Optional |
Integer specifying a default expiration for bypass codes generated by Help Desk admins, in minutes. If not set, Help Desk admins may change bypass code expiration from the default 60 minutes after creation if helpdesk_bypass is set to allow . If specifying a value, also set helpdesk_bypass to limit .
|
||||||||||
helpdesk_can_send_enroll_email
|
Optional |
Permits Help Desk administrators to send or resend enrollment emails to users. Set to true to allow sending of enrollment emails. Default value is false .
|
||||||||||
helpdesk_message
|
Optional | Legacy parameter; no effect if specified. Use the Modify Custom Messaging endpoint. | ||||||||||
inactive_user_expiration
|
Optional |
Users will be automatically deleted if they are inactive (no successful logins) for this number of days.
Minimum: 30
Maximum: 365
|
||||||||||
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
Maximum: 30000
|
||||||||||
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. Default is 10 attempts.
Minimum: 1
Maximum: 9999
|
||||||||||
log_retention_days
|
Optional |
When set, log entries older than the specified number of days are purged. Logs retained indefinitely if null . Note that the log retention setting does not change the 180 day limitation for viewing and retrieving log information in the Duo Admin Panel, exported reports, or via this API.
Default: null (no retention limit).
Minimum: 1 day.
Maximum: 365 days.
|
||||||||||
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 .
Minimum: 12
Maximum: 100
|
||||||||||
mobile_otp_enabled
|
Optional |
Legacy parameter; no effect if specified and always returns |
||||||||||
name
|
Optional |
Sets the customer name. |
||||||||||
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_activity_notification_enabled
|
Optional |
If true , users will receive a Duo Mobile notification when an authentication device is added or removed. If set to false , no email notifications are sent in these situations. Default value is false .
|
||||||||||
push_enabled
|
Optional |
Legacy parameter; no effect if specified and always returns |
||||||||||
sms_batch
|
Optional | The number of passcodes to send at one time, up to 10. | ||||||||||
sms_enabled
|
Optional |
Legacy parameter; no effect if specified and always returns |
||||||||||
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 Duo Admin Panel. Timezones must be entries in the IANA Time Zone Database, for example, "US/Eastern", "Australia/Darwin", "GMT". | ||||||||||
u2f_enabled
|
Optional |
Legacy parameter; no effect if specified. Use Duo Authentication Method policies to configure this setting. |
||||||||||
unenrolled_user_lockout_threshold
|
Optional |
If non-zero, this is the number of days users can be unenrolled for before they are put into a locked out status. If |
||||||||||
user_managers_can_put_users_in_bypass
|
Optional |
Permits User Manager administrators to apply "Bypass" status to users. Set to |
||||||||||
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. If you know the countries from which your users expect to authenticate with phone callback we recommend adjusting this down from the default to match the most expensive expected country to help avoid misuse, using the values from the Telephony Credits documentation.
Default: 20 .
|
||||||||||
voice_enabled
|
Optional |
Legacy parameter; no effect if specified and always returns |
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 Logo
Returns the custom logo displayed in the Duo authentication prompt and Duo Mobile. Requires "Grant settings API permission.
This logo customization is superseded by Custom Branding for Duo Premier, Advantage, and Essentials plan customers. Migrate to the new custom branding endpoint for increased functionality. This endpoint is deprecated and will stop working in a future update.
GET /admin/v1/logo
Parameters
This API endpoint has no parameters.
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 Logo
Returns the custom logo displayed in the Duo authentication prompt and 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.
This logo customization is superseded by Custom Branding for Duo Premier, Advantage, and Essentials plan customers. Migrate to the new custom branding endpoint for increased functionality. This endpoint is deprecated and will stop working in a future update.
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. |
600 | Incorrect PNG base64 encoding. |
Response Format
Empty string.
Delete Logo
Remove the logo from the Duo authentication prompt and future activation of Duo Mobile. Currently enrolled devices must be re-activated to remove the logo. Requires "Grant settings" API permission.
This logo customization is superseded by Custom Branding for Duo Premier, Advantage, and Essentials plan customers. Migrate to the new custom branding endpoint for increased functionality. This endpoint is deprecated and will stop working in a future update. Logo updates made to this endpoint have no effect.
DELETE /admin/v1/logo
Parameters
This API endpoint has no parameters.
Response Codes
Response | Meaning |
---|---|
200 | The logo was deleted or did not exist. |
Response Format
Empty string.
Custom Branding
Custom branding is available to Duo Premier, Duo Advantage, and Duo Essentials plan customers.
Retrieve Live Custom Branding
Returns effective custom branding settings. These settings can also be viewed and set in the Duo Admin Panel. Requires "Grant settings" API permission.
GET /admin/v1/branding
Parameters
This API endpoint has no parameters.
Response Codes
Response | Meaning |
---|---|
200 | Success. Returns live branding. |
Response Format
Key | Value |
---|---|
background_img
|
A base64 encoded background image in PNG format. Shown in Duo SSO and Duo Universal Prompt. |
card_accent_color
|
A CSS hex color shown as the hash symbol (#) followed by three or six hexadecimal digits, which represents the colored line appearing at the top of the interactive user interface. Shown in Duo SSO and Universal Prompt. |
logo
|
A base64 encoded logo image in PNG format. Shown in Duo SSO, Duo Universal Prompt, and traditional prompt. |
page_background_color
|
A CSS hex color shown as the hash symbol (#) followed by three or six hexadecimal digits, which represents the color appearing below the user interface and beneath any transparent background image. Shown in Duo SSO and Universal Prompt. |
powered_by_duo
|
If true , Duo SSO, Duo Universal Prompt, and traditional prompt show the "Secured by Duo" branding. Otherwise, false .
|
sso_custom_username_label
|
A string that is displayed for the custom SSO Login Label. |
Example Response
{
"stat": "OK",
"response": {
"background_image": "iVBORw0KGgoAAAANSUhEUgAABQAAAAMgCAYAAAB8mM/7AAABrmlUWHRYTUw6Y29tLmFkb2JlLnhtcAAAAAAAPD94cGFja2V0IGJlZ2luPSLvu78iIGlkPSJXNU0wTXBDZWhpSHpyZVN6TlRjemtjOWQiPz4KPHg6eG1wbWV0YSB4bWxuczp4PSJhZG9iZTpuczptZXRhLyIgeDp4bXB0az0iQWRvYmUgWE1QIENvcmUgNi4wLWMwMDYgNzkuMTY0NzUzLCAyMDIxLzAyLzE1LTExOjUyOjEzICAgICAgICAiPgogPHJkZjpSREYggg==",
"card_accent_color": "#144A94",
"logo": "iVBORw0KGgoAAAANSUhEUgAAARQAAAEwCAYAAAB2TY5ZAAAACXBIWXMAAAwHAAAMBwF2myPLAAA55mlUWHRYTUw6Y29tLmFkb2JlLnhtcAAAAAAAPD94cGFja2V0IGJlZ2luPSLvu78iIGlkPSJXNU0wTXBDZWhpSHpyZVN6TlRjemtjOWQiPz4KPHg6eG1wbWV0YSB4bWxuczp4PSJhZG9iZTpuczptZXRhLyIgeDp4bXB0az0iQWRvYmUgWE1QIENvcmUgNS42LWMxMzggNzkuMTU5ODI0LCAyMDE2LzA5LzE0LTAxOjA5OjAxICAgICAgIkJggg==",
"page_background_color": "#437BC6",
"powered_by_duo": true,
"sso_custom_username_label": "Username"
}
}
Modify Live Custom Branding
Change effective custom branding settings. These settings can also be viewed and set in the Duo Admin Panel. Requires "Grant settings" API permission.
POST /admin/v1/branding
Parameters
Parameter | Required? | Description |
---|---|---|
background_img
|
Optional | A base64 encoded background image in PNG format, with maximum size less than 3MB and dimensions between 12 by 12 pixels and 3840 by 2160 pixels. Shown in Duo SSO and Duo Universal Prompt. |
card_accent_color
|
Optional | A CSS hex color shown as the hash symbol (#) followed by three or six hexadecimal digits, which represents the colored line appearing at the top of the interactive user interface. Shown in Duo SSO and Universal Prompt. |
logo
|
Optional | A base64 encoded logo image in PNG format, with maximum size less than 200KB and dimensions between 12 by 12 pixels and 500 by 500 pixels. Shown in Duo SSO, Duo Universal Prompt, and traditional prompt. |
page_background_color
|
Optional | A CSS hex color shown as the hash symbol (#) followed by three or six hexadecimal digits, which represents the color appearing behind the user interface and any transparent background image. Shown in Duo SSO and Universal Prompt. |
powered_by_duo
|
Optional |
If true , Duo SSO, Duo Universal Prompt, and traditional prompt show the "Secured by Duo" branding. Otherwise, false .
|
sso_custom_username_label
|
Optional |
Specify the string that is displayed for the custom SSO Login Label. Can be Username , Email Address , or a custom string. The custom string can only contain letters and numbers (maximum length 100 characters). No effect unless Duo SSO is enabled and configured.
|
Response Codes
Response | Meaning |
---|---|
200 | The live branding settings were modified successfully. The settings objects are also returned (see Retrieve Live Custom Branding). |
400 |
Invalid or missing parameters.
For example, card_accent_color an invalid HTML hex code.
|
600 | Incorrect PNG base64 encoding of logo or background images. |
Response Format
Same as Retrieve Live Custom Branding.
Example Response
Same as Retrieve Live Custom Branding.
Retrieve Draft Custom Branding
Returns saved draft custom branding settings. These settings can also be viewed and set in the Duo Admin Panel. Requires "Grant settings" API permission.
GET /admin/v1/branding/draft
Parameters
This API endpoint has no parameters.
Response Codes
Response | Meaning |
---|---|
200 | Success. Returns draft branding. |
Response Format
Key | Value |
---|---|
background_img
|
A base64 encoded background image in PNG format. Shown in Duo SSO and Duo Universal Prompt. |
card_accent_color
|
A CSS hex color shown as the hash symbol (#) followed by three or six hexadecimal digits, which represents the colored line appearing at the top of the interactive user interface. Shown in Duo SSO and Universal Prompt. |
draft_user
|
A list of test users who see draft branding (if configured) instead of live branding when using Duo SSO or Duo Universal Prompt.See Retrieve Users for descriptions of the response fields. |
logo
|
A base64 encoded logo image in PNG format. Shown in Duo SSO, Duo Universal Prompt, and traditional prompt. |
page_background_color
|
A CSS hex color shown as the hash symbol (#) followed by three or six hexadecimal digits, which represents the color appearing behind the user interface and any transparent background image. Shown in Duo SSO and Universal Prompt. |
powered_by_duo
|
If true , Duo SSO, Duo Universal Prompt, and traditional prompt show the "Secured by Duo" branding. Otherwise, false .
|
sso_custom_username_label
|
A string that is displayed for the custom SSO Login Label. |
Example Response
{
"stat": "OK",
"response": {
"background_image": "iVBORw0KGgoAAAANSUhEUgAABQAAAAMgCAYAAAB8mM/7AAABrmlUWHRYTUw6Y29tLmFkb2JlLnhtcAAAAAAAPD94cGFja2V0IGJlZ2luPSLvu78iIGlkPSJXNU0wTXBDZWhpSHpyZVN6TlRjemtjOWQiPz4KPHg6eG1wbWV0YSB4bWxuczp4PSJhZG9iZTpuczptZXRhLyIgeDp4bXB0az0iQWRvYmUgWE1QIENvcmUgNi4wLWMwMDYgNzkuMTY0NzUzLCAyMDIxLzAyLzE1LTExOjUyOjEzICAgICAgICAiPgogPHJkZjpSREYggg==",
"card_accent_color": "#144A94",
"draft_users": [{
"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",
"external_id": "1a2345b6-7cd8-9e0f-g1hi-23j45kl6m789",
"firstname": "",
"is_enrolled": true,
"last_directory_sync": 1384275337,
"last_login": 1514922986,
"lastname": "",
"notes": "",
"realname": "Joe Smith",
"status": "active",
"user_id": "DU3RP9I2WOC59VZX672N",
"username": "jsmith",
}],
"logo": "iVBORw0KGgoAAAANSUhEUgAAARQAAAEwCAYAAAB2TY5ZAAAACXBIWXMAAAwHAAAMBwF2myPLAAA55mlUWHRYTUw6Y29tLmFkb2JlLnhtcAAAAAAAPD94cGFja2V0IGJlZ2luPSLvu78iIGlkPSJXNU0wTXBDZWhpSHpyZVN6TlRjemtjOWQiPz4KPHg6eG1wbWV0YSB4bWxuczp4PSJhZG9iZTpuczptZXRhLyIgeDp4bXB0az0iQWRvYmUgWE1QIENvcmUgNS42LWMxMzggNzkuMTU5ODI0LCAyMDE2LzA5LzE0LTAxOjA5OjAxICAgICAgIkJggg==",
"page_background_color": "#437BC6",
"powered_by_duo": true,
"sso_custom_username_label": "Username"
}
}
Modify Draft Custom Branding
Change draft custom branding settings. These settings can also be viewed and set in the Duo Admin Panel. Requires "Grant settings" API permission.
POST /admin/v1/branding/draft
Parameters
Parameter | Required? | Description |
---|---|---|
background_img
|
Optional | A base64 encoded background image in PNG format, with maximum size less than 3MB and dimensions between 12 by 12 pixels and 3840 by 2160 pixels. Shown in Duo SSO and Duo Universal Prompt. |
card_accent_color
|
Optional | A CSS hex color shown as the hash symbol (#) followed by three or six hexadecimal digits, which represents the colored line appearing at the top of the interactive user interface. Shown in Duo SSO and Universal Prompt. |
logo
|
Optional | A base64 encoded logo image in PNG format, with maximum size less than 200KB and dimensions between 12 by 12 pixels and 500 by 500 pixels. Shown in Duo SSO, Duo Universal Prompt, and traditional prompt. |
page_background_color
|
Optional | A CSS hex color shown as the hash symbol (#) followed by three or six hexadecimal digits, which represents the color appearing below the user interface and beneath any transparent background image. Shown in Duo SSO and Universal Prompt. |
powered_by_duo
|
Optional |
If true , Duo SSO, Duo Universal Prompt, and traditional prompt show the "Secured by Duo" branding. Otherwise, false .
|
sso_custom_username_label
|
Optional |
Specify the string that is displayed for the custom SSO Login Label. Can be Username , Email Address , or a custom string (maximum length 100 characters). The custom string can only contain letters and numbers. No effect unless Duo SSO is enabled and configured.
|
user_ids
|
Optional | A comma separated list of user IDs that will see saved draft branding in Duo SSO and Duo Universal Prompt. |
Response Codes
Response | Meaning |
---|---|
200 | The draft branding settings were modified successfully. The settings objects are also returned (see Retrieve Live Custom Branding). |
400 |
Invalid or missing parameters.
For example, card_accent_color an invalid HTML hex code.
|
600 | Incorrect PNG base64 encoding of logo or background images. |
Response Format
Same as Retrieve Draft Custom Branding.
Example Response
Same as Retrieve Draft Custom Branding.
Add Draft Custom Branding User by ID
Add a single user with ID user_id
to the list of draft branding test users. Requires "Grant settings" API permission.
POST /admin/v1/branding/draft/users/[user_id]
Parameters
This API endpoint has no parameters.
Response Codes
Response | Meaning |
---|---|
200 |
The user was added to the draft branding user list successfully. The draft branding object is also returned (see Retrieve Draft Custom Branding). |
404 |
No user was found with the given |
Response Format
Same as Retrieve Draft Custom Branding.
Example Response
Same as Retrieve Draft Custom Branding.
Remove Draft Custom Branding User by ID
Remove a single user with ID user_id
from the list of draft branding test users. Requires "Grant settings" API permission.
DELETE /admin/v1/branding/draft/users/[user_id]
Parameters
This API endpoint has no parameters.
Response Codes
Response | Meaning |
---|---|
200 |
The user was removed from the draft branding user list successfully. The draft branding object is also returned (see Retrieve Draft Custom Branding). |
404 |
No user was found with the given |
Response Format
Same as Retrieve Draft Custom Branding.
Example Response
Same as Retrieve Draft Custom Branding.
Publish Draft Custom Branding as Live Custom Branding
Replaces the current live custom branding with the draft custom branding for all users and then removes the draft branding. Requires "Grant settings" API permission.
POST /admin/v1/branding/draft/publish
Parameters
This API endpoint has no parameters.
Response Codes
Response | Meaning |
---|---|
200 |
Success. |
Response Format
Same as Retrieve Live Custom Branding.
Example Response
Same as Retrieve Live Custom Branding.
Retrieve Custom Messaging
Returns effective custom messaging settings, shown to users in the Universal Prompt. These settings can also be viewed and set in the Duo Admin Panel. Supersedes the helpdesk_message Settings parameter. Requires "Grant settings" API permission.
GET /admin/v1/branding/custom_messaging
Parameters
This API endpoint has no parameters.
Response Codes
Response | Meaning |
---|---|
200 | Success. Returns custom messaging. |
Response Format
Key | Value | ||||
---|---|---|---|---|---|
help_links
|
A comma-separated list of up to two custom external links shown to users in the Universal Prompt. Must begin with |
||||
help_text_by_locale
|
Customized text string associated with the specified locale. The user's browser's preferred language settings determine which language to show in the Universal Prompt. The first locale and message text in the list matches the default language specified in global Settings and is also shown in the traditional web prompt and in Duo Desktop.
|
Example Response
{
"stat": "OK",
"response": {
"help_links": [
"https://helpme.acme.corp"
],
"help_text_by_locale": [
{
"help_text": "Contact the Acme Service Desk at 888-555-5310.",
"locale": "en_US"
},
{
"help_text": "Contactez le Service Desk Acme au 888-555-5310.",
"locale": "fr_FR"
}
]
}
}
Modify Custom Messaging
Updates current custom messaging settings, shown to users in the Universal Prompt. These settings can also be viewed and set in the Duo Admin Panel. Supersedes the helpdesk_message Settings parameter. Requires "Grant settings" API permission.
POST /admin/v1/branding/custom_messaging
Parameters
Parameter | Required? | Description |
---|---|---|
help_links
|
Optional | A comma-separated list of up to two custom external links shown to users in the Universal Prompt. Each URL must begin with |
help_text
|
Optional |
Customized text string associated with the specified locale. The user's browser's preferred language settings determine which language to show in the Universal Prompt. The first locale and message text in the list matches the default language specified in global Settings and is also shown in the traditional web prompt and in Duo Desktop. Up to 200 characters. No support for hyperlinks. |
locale
|
Required if help_text is specified. Otherwise, optional.
|
The language of the help text. One of: |
Response Codes
Response | Meaning |
---|---|
200 |
The custom messaging settings were updated. The settings objects are also returned (see Retrieve Custom Messaging). |
400 |
Invalid or missing parameters.
For example, |
Response Format
Same as Retrieve Custom Messaging.
Example Response
Same as Retrieve Custom Messaging.
Account Info
Retrieve Summary
Returns a summary of account utilization information. Requires "Grant read information" API permission.
GET /admin/v1/info/summary
Parameters
This API endpoint has no parameters.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
Response Format
Key | Value |
---|---|
admin_count
|
Current number of admins in the account. |
edition
|
Current edition (including trials) of 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. |
user_pending_deletion_count
|
Current number of users pending deletion from the account (seen in the Admin Panel's Trash view). |
Example Response
{
"stat": "OK",
"response": {
"admin_count": 21,
"edition": "Duo Premier",
"integration_count": 44,
"telephony_credits_remaining": 960,
"user_count": 862,
"user_pending_deletion_count": 9
}
}
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
|
An integer indicating the Unix timestamp in seconds for the beginning of the report period. |
maxtime
|
An integer indicating the Unix timestamp in seconds for the end of the report period. |
telephony_credits_used
|
An integer indicating the number of telephony credits consumed 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
|
An integer indicating the Unix timestamp in seconds for the beginning of the report period. | ||||||||||
maxtime
|
An integer indicating the Unix timestamp in seconds for the end of the report period. | ||||||||||
authentication_attempts
|
An integer indicating the number of authentication attempts during the specified time period, broken down by result:
|
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
|
An integer indicating the Unix timestamp in seconds for the beginning of the report period. |
maxtime
|
An integer indicating the Unix timestamp in seconds for the end of the report period. |
user_authentication_attempts
|
An integer indicating the 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.