Try Duo's trusted access solution now.
Free TrialThe Admin API provides programmatic access to the administrative functionality of Duo Security's two-factor authentication platform.
The Admin API lets developers integrate with Duo Security’s platform at a low level. The API has methods for creating, retrieving, updating, and deleting the core objects in Duo’s system: users, phones, hardware tokens, admins, and integrations.
In addition, developers can write applications that programmatically read their Duo account’s authentication logs, administrator logs, and telephony logs; read or update account settings; and retrieve reports and other information.
Review the API Details to see how to construct your first API request.
This API is available to Duo Beyond, Duo Access, and Duo MFA plan customers.
Documented properties will not be removed within a stable version of the API. Once a given API endpoint is documented to return a given property, a property with that name will always appear (although certain properties may only appear under certain conditions, like if the customer is using a specific edition).
Properties that enumerate choices may gain new values at any time, e.g. the device platform
value could return new device platforms that did not previously exist. Duo will update our API documentation with new values in a timely fashion.
New, undocumented properties may also appear at any time. For instance, Duo may make available a beta feature involving extra information returned by an API endpoint. Until the property is documented here its format may change or it may even be entirely removed from our API.
We have started implementing v2 handlers for endpoints. In these cases, the API v1 handler remains supported, but will be limited or deprecated in the future. We encourage use of the v2 endpoints where available and recommend migrating existing API implementations to the v2 handlers.
Please note that all Unix timestamps are in seconds.
The security of your Duo application is tied to the security of your secret key (skey). Secure it as you would any sensitive credential. Don't share it with unauthorized individuals or email it to anyone under any circumstances!
Permission | Details |
---|---|
Grant administrators | The Admin API application can create, update, and delete Duo administrators. |
Grant read information | The Admin API application can read reporting information. |
Grant applications | The Admin API application can create, update, and delete Duo 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, telephony, and administrator action log information. |
Grant read resource | The Admin API application can read information about resource objects such as users and devices. |
Grant write resource | The Admin API application can create, update, and delete resource objects such as users and devices. |
Duo Security has demonstration clients available on Github to call the Duo API methods. Examples are available in: Python, Java, C#, Ruby, Perl, and PHP.
This integration communicates with Duo’s service on TCP port 443. Also, we do not recommend locking down your firewall to individual IP addresses, since these may change over time to maintain our service’s high availability.
All API methods use your API hostname,
https://api-XXXXXXXX.duosecurity.com
.
Methods always use HTTPS. Unsecured HTTP is not supported.
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.
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. |
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 the endpoint does not support paged results or the total results do not exceed one page.
Specifying incorrect paging parameters results in a 400
invalid parameters response.
Metadata Information | Description |
---|---|
total_objects
|
The total number of objects retrieved by the API request across all pages of results. |
next_offset
|
The offset from 0 at which to start the next paged set of results. If not present in the metadata response, then there are no more pages of results left. |
prev_offset
|
The offset from 0 at which the previous paged set of results started. If you did not specify |
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 0 at which to start record retrieval. When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: 0 |
To retrieve the full set of results for a request with paged results, repeat the call, specifying the offset
parameter value, until there are no more results (indicated by the absence of next_offset
).
Paging Metadata Examples:
The metadata response will look like these examples except where noted for an individual API endpoint.
This metadata information indicates that there are 951 total objects returned by that endpoint, and no offset
or limit
was specified so the response set defaulted to the first 100 objects:
{
"metadata": {
"next_offset": 100,
"prev_offset": 0,
"total_objects": 951
}
This metadata information indicates that the request specified offset=500 limit=200
, so the response set was objects 500-699:
{
"metadata": {
"next_offset": 700,
"prev_offset": 300,
"total_objects": 11318
}
This metadata information indicates that there are 2342 total objects, and the request specified offset=2300
and used that endpoint's default limit
of 100, so the response set was the end of the list (objects 2300-2342):
{
"metadata": {
"prev_offset": 2200,
"total_objects": 2342
}
The API uses HTTP Basic Authentication to authenticate requests. Use your Duo application’s integration key as the HTTP Username.
Generate the HTTP Password as an HMAC signature of the request. This will be different for each request and must be re-generated each time.
To construct the signature, first build an ASCII string from your request, using the following components:
Component | Description | Example |
---|---|---|
date
|
The current time, formatted as RFC 2822. This must be the same string as the “Date” header. |
Tue, 21 Aug 2012 17:29:18 -0000
|
method
|
The HTTP method (uppercase) |
POST
|
host
|
Your API hostname (lowercase) |
api-xxxxxxxx.duosecurity.com
|
path
|
The specific API method’s path |
/admin/v1/users
|
params
|
The URL-encoded list of key=value pairs, lexicographically sorted by key. These come from the request parameters (the URL query string for GET and DELETE requests or the request body for POST requests).
If the request does not have any parameters one must still include a blank line in the string that is signed.
Do not encode unreserved characters. Use upper-case hexadecimal digits A through F in escape sequences.
|
realname=First%20Last&username=root
|
Then concatenate these components with (line feed) newlines. For example:
Tue, 21 Aug 2012 17:29:18 -0000
POST
api-xxxxxxxx.duosecurity.com
/admin/v1/users
realname=First%20Last&username=root
GET requests also use this five-line format:
Tue, 21 Aug 2012 17:29:18 -0000
GET
api-xxxxxxxx.duosecurity.com
/admin/v1/users
username=root
Lastly, compute the HMAC-SHA1 of this canonical representation, using your Duo Admin API application’s secret key as the HMAC key. Send this signature as hexadecimal ASCII (i.e. not raw binary data). Use HTTP Basic Authentication for the request, using your integration key as the username and the HMAC-SHA1 signature as the password. Signature validation is case-insensitive, so the signature may be upper or lowercase.
For example, here are the headers for the above POST request to api-XXXXXXXX.duosecurity.com/admin/v1/users
, using DIWJ8X6AEYOR5OMC6TQ1
as the integration key and Zh5eGmUq9zpfQnyUIu5OL9iWoMMv5ZNmk3zLJ4Ep
as the secret key:
Date: Tue, 21 Aug 2012 17:29:18 -0000
Authorization: Basic RElXSjhYNkFFWU9SNU9NQzZUUTE6MmQ5N2Q2MTY2MzE5NzgxYjVhM2EwN2FmMzlkMzY2ZjQ5MTIzNGVkYw==
Host: api-XXXXXXXX.duosecurity.com
Content-Length: 35
Content-Type: application/x-www-form-urlencoded
Separate HTTP request header lines CRLF newlines.
The following Python function can be used to construct the “Authorization” and “Date” headers:
import base64, email, hmac, hashlib, urllib
def sign(method, host, path, params, skey, ikey):
"""
Return HTTP Basic Authentication ("Authorization" and "Date") headers.
method, host, path: strings from request
params: dict of request parameters
skey: secret key
ikey: integration key
"""
# create canonical string
now = email.Utils.formatdate()
canon = [now, method.upper(), host.lower(), path]
args = []
for key in sorted(params.keys()):
val = params[key]
if isinstance(val, unicode):
val = val.encode("utf-8")
args.append(
'%s=%s' % (urllib.quote(key, '~'), urllib.quote(val, '~')))
canon.append('&'.join(args))
canon = '\n'.join(canon)
# sign canonical string
sig = hmac.new(skey, canon, hashlib.sha1)
auth = '%s:%s' % (ikey, sig.hexdigest())
# return headers
return {'Date': now, 'Authorization': 'Basic %s' % base64.b64encode(auth)}
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.
GET /admin/v1/users
Parameters
Paging Parameter | Required? | Description |
---|---|---|
limit
|
Optional |
The maximum number of records returned. Default: 100; Max: 300 |
offset
|
Optional |
The offset from 0 at which to start record retrieval. When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: 0 |
Query Parameter | Required? | Description |
---|---|---|
username
|
Optional | Specify a username 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). Up to four aliases may exist. |
||||||||||||
created
|
The user's creation date timestamp. |
||||||||||||
email
|
The user’s email address. |
||||||||||||
firstname
|
The user’s given name. Required for Duo's ID Proofing feature. |
||||||||||||
groups
|
List of groups to which this user belongs. |
||||||||||||
is_enrolled
|
Is "true" if the user has a phone, hardware token, U2F token, or security key available for authentication. Otherwise, "false". |
||||||||||||
last_directory_sync
|
Timestamp of the last update to the user via directory sync, or “null” if the user has never synced with an external directory or if the directory that originally created the user has been deleted from Duo. |
||||||||||||
last_login
|
The last time this user logged in, as a UNIX timestamp, or “null” if the user has not logged in. |
||||||||||||
lastname
|
The user’s surname. Required for Duo's ID Proofing feature. |
||||||||||||
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. See Retrieve U2F Tokens for descriptions of the response values. |
||||||||||||
user_id
|
The user’s ID. |
||||||||||||
username
|
The user’s username. |
||||||||||||
webauthncredentials
|
A list of WebAuthn authenticators that this user can use. See Retrieve WebAuthn Credentials by User ID for descriptions of the response values. |
Example Response
{
"stat": "OK",
"response": [{
"alias1": "joe.smith",
"alias2": "jsmith@example.com",
"alias3": null,
"alias4": null,
"created": 1489612729,
"email": "jsmith@example.com",
"firstname": "Joe",
"groups": [{
"desc": "People with hardware tokens",
"name": "token_users"
}],
"is_enrolled": true,
"last_directory_sync": 1508789163,
"last_login": 1343921403,
"lastname": "Smith",
"notes": "",
"phones": [{
"activated": true,
"capabilities": [
"auto",
"push",
"sms",
"phone",
"mobile_otp"
],
"encrypted": "Encrypted",
"extension": "",
"fingerprint": "Configured",
"last_seen": "2019-11-18T15:51:13",
"model": "Apple iPhone 11 Pro",
"name": "My iPhone",
"number": "15555550100",
"phone_id": "DPFZRS9FB0D46QFTM899",
"platform": "Apple iOS",
"postdelay": "0",
"predelay": "0",
"screenlock": "Locked",
"sms_passcodes_sent": true,
"tampered": "Not tampered",
"type": "Mobile"
}],
"realname": "Joe Smith",
"status": "active",
"tokens": [{
"serial": "0",
"token_id": "DHIZ34ALBA2445ND4AI2",
"type": "d1"
}],
"u2ftokens": [{
"date_added": "1444678994",
"registration_id": "D21RU6X1B1DF5P54B6PV"
}],
"user_id": "DU3RP9I2WOC59VZX672N",
"username": "jsmith",
"webauthncredentials": [
{
"credential_name": "Touch ID",
"date_added": 1550685154,
"label": "Touch ID",
"webauthnkey": "WABFEOE007ZMV1QAZTRB"
},
{
"credential_name": "YubiKey C",
"date_added": 1550674764,
"label": "Security Key",
"webauthnkey": "WA4BD9AUVMSNUFWZGES4"
}],
}]
}
Create a new user with the specified username
.
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. Aliases must be unique amongst users. |
||||||||
realname
|
Optional |
The real name (or full name) of this user. |
||||||||
email
|
Optional |
The email address of this user. |
||||||||
status
|
Optional |
The user’s status. One of:
|
||||||||
notes
|
Optional |
An optional description or notes field. Can be viewed in the Admin Panel. |
||||||||
firstname
|
Optional |
The user’s given name. Required for Duo's ID Proofing feature. |
||||||||
lastname
|
Optional |
The user’s surname. Required for Duo's ID Proofing feature. |
Response Codes
Response | Meaning |
---|---|
200 | Success. Returns the newly created user. |
400 |
Invalid or missing parameters, or user already exists with the given username .
|
Response Format
Returns the single object created. Refer to Retrieve Users for an explanation of the object’s keys.
Example Response
{
"stat": "OK",
"response": [{
"alias1": "joe.smith",
"alias2": "jsmith@example.com",
"alias3": null,
"alias4": null,
"created": 1489612729,
"email": "jsmith@example.com",
"firstname": "Joe",
"groups": [],
"is_enrolled": false,
"last_directory_sync": null,
"last_login": null,
"lastname": "Smith",
"notes": "",
"phones": [],
"realname": "Joe Smith",
"status": "active",
"tokens": [],
"u2ftokens": [],
"user_id": "DU3RP9I2WOC59VZX672N",
"username": "jsmith",
}]
}
Return the single user with user_id
.
GET /admin/v1/users/[user_id]
Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
404 |
No user was found with the given user_id .
|
Response Format
Returns a single object. Refer to Retrieve Users for an explanation of the object’s keys.
Example Response
Same as Retrieve User.
Change the username, username aliases, full name, status, and/or notes section of the user with ID user_id
.
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. Aliases must be unique amongst users. |
realname
|
Optional |
The new real name (or full name). |
email
|
Optional |
The new email address. |
status
|
Optional |
The new status. Must be one of “active”, “disabled”, or “bypass”. See Retrieve Users for an explanation of these fields. |
notes
|
Optional |
The new notes field. |
firstname
|
Optional |
The user’s new given name. Required for Duo's ID Proofing feature. |
lastname
|
Optional |
The user’s new surname. Required for Duo's ID Proofing feature. |
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
Same as Retrieve Users.
Example Response
Same as Retrieve User by ID.
Delete the user with ID user_id
from the system.
DELETE /admin/v1/users/[user_id]
Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | The user was deleted or did not exist. |
Response Format
Empty string.
Example Response
{
"stat": "OK",
"response": ""
}
Enroll a user with user name username
and email address email
and send them an enrollment email that expires after valid_secs
seconds.
POST /admin/v1/users/enroll
Parameters
Parameter | Required? | Description |
---|---|---|
username |
Required | The name of the user to enroll. |
email |
Required | The email address of this user. |
valid_secs |
Optional | The number of seconds the enrollment code should be valid for. Default: 2592000 (30 days). |
Response Codes
Response | Meaning |
---|---|
200 | The enrollment code was generated and the user was sent an enrollment email. The newly created enrollment code is also returned. |
400 | Invalid or missing parameter(s), or the user with the given username and email address already exists and is enrolled. |
Response Format
Single string (the enrollment code).
Example Response
{
"stat": "OK",
"response": "00d70e730b22cb66"
}
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.
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. |
valid_secs
|
Optional | The number of seconds generated bypass codes should be valid for. If 0 (the default) the codes will never expire. |
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. |
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"
]
}
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.
GET /admin/v1/users/[user_id]/bypass_codes
Parameters
Paging Parameter | Required? | Description |
---|---|---|
limit
|
Optional |
The maximum number of records returned. Default: 100; Max: 500 |
offset
|
Optional |
The offset from 0 at which to start record retrieval. When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: 0 |
Query Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
404 |
No user was found with the given user_id .
|
Response Format
Key | Value |
---|---|
admin_email
|
The email address of the Duo administrator who created the bypass code. |
bypass_code_id
|
The bypass code's identifier. Use with GET bypass code by ID. |
created
|
The bypass code creation date timestamp. |
expiration
|
The expiration timestamp of the bypass code, or "null" if the bypass code does not expire on a certain date. |
reuse_count
|
The number of times the bypass code may be used before expiring, or "null" if the bypass code has no limit on the number of times it may be used. |
Example Response
{
"stat": "OK",
"response": [{
"bypass_code_id": "DB2A9F0012RL54001FA3",
"created": 1522260759,
"expiration": 1522264359,
"reuse_count": 1
}]
}]
}
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.
GET /admin/v1/users/[user_id]/groups
Parameters
Paging Parameter | Required? | Description |
---|---|---|
limit
|
Optional |
The maximum number of records returned. Default: 100; Max: 500 |
offset
|
Optional |
The offset from 0 at which to start record retrieval. When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: 0 |
Query Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
404 |
No user was found with the given user_id .
|
Response Format
Same as for Retrieve Groups.
Example Response
{
"response": [{
"desc": "This is group A",
"group_id": "DGXXXXXXXXXXXXXXXXXX",
"name": "Group A"
},
{
"desc": "This is group B",
"group_id": "DGXXXXXXXXXXXXXXXXXX",
"name": "Group B"
}],
"stat": "OK"
}
Associate a group with the user with ID user_id
.
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 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.
DELETE /admin/v1/users/[user_id]/groups/[group_id]
Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | Success, or no such group exists. |
404 |
No user was found with the given user_id .
|
Response Format
Empty string.
Example Response
{
"stat": "OK",
"response": ""
}
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.
GET /admin/v1/users/[user_id]/phones
Parameters
Paging Parameter | Required? | Description |
---|---|---|
limit
|
Optional |
The maximum number of records returned. Default: 100; Max: 500 |
offset
|
Optional |
The offset from 0 at which to start record retrieval. When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: 0 |
Query Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
404 |
No user was found with the given user_id .
|
Response Format
Same as for Retrieve Phones, except phones have no users
attribute.
Example Response
{
"stat": "OK",
"response": [{
"activated": false,
"capabilities": [
"sms",
"phone",
"push"
],
"encrypted": "Encrypted",
"extension": "",
"fingerprint": "Configured",
"last_seen": "2019-03-04T15:04:04",
"model": "Google Pixel 2 Xl",
"name": "",
"number": "+15035550102",
"phone_id": "DPFZRS9FB0D46QFTM890",
"platform": "Google Android",
"postdelay": "",
"predelay": "",
"screenlock": "Locked",
"sms_passcodes_sent": true,
"tampered": "Not tampered",
"type": "Mobile"
},
{
"activated": false,
"capabilities": [
"phone"
].
"encrypted": "",
"extension": "",
"fingerprint": "",
"last_seen": "",
"model": "Unknown",
"name": "",
"number": "+15035550103",
"phone_id": "DPFZRS9FB0D46QFTM891",
"platform": "Unknown",
"postdelay": "",
"predelay": "",
"screenlock": "",
"sms_passcodes_sent": false,
"tampered": "",
"type": "Landline"
}]
}
Associate a phone with the user with ID user_id
.
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 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.
DELETE /admin/v1/users/[user_id]/phones/[phone_id]
Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | Success, or no such phone exists. |
404 |
No user was found with the given user_id .
|
Response Format
Empty string.
Example Response
{
"stat": "OK",
"response": ""
}
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.
GET /admin/v1/users/[user_id]/tokens
Parameters
Paging Parameter | Required? | Description |
---|---|---|
limit
|
Optional |
The maximum number of records returned. Default: 100; Max: 500 |
offset
|
Optional |
The offset from 0 at which to start record retrieval. When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: 0 |
Query Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
404 |
No user was found with the given user_id .
|
Response Format
Same as for Retrieve Hardware Tokens, except hardware tokens have no users
attribute.
Example Response
{
"stat": "OK",
"response": [{
"type": "d1",
"serial": "0",
"token_id": "DHEKH0JJIYC1LX3AZWO4"
},
{
"type": "d1",
"serial": "7",
"token_id": "DHUNT3ZVS3ACF8AEV2WG",
"totp_step": null
}]
}
Associate a hardware token with the user with ID user_id
.
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 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.
DELETE /admin/v1/users/[user_id]/tokens/[token_id]
Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
404 |
No user was found with the given user_id
|
Response Format
Empty string.
Example Response
{
"stat": "OK",
"response": ""
}
Returns a paged list of U2F tokens associated with the user with ID user_id
. To fetch all results, call repeatedly with the offset parameter as long as the result metadata has a next_offset
value.
GET /admin/v1/users/[user_id]/u2ftokens
Parameters
Paging Parameter | Required? | Description |
---|---|---|
limit
|
Optional |
The maximum number of records returned. Default: 100; Max: 500 |
offset
|
Optional |
The offset from 0 at which to start record retrieval. When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: 0 |
Query Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
404 |
No user was found with the given user_id .
|
Response Format
Same as for Retrieve U2F Tokens, except U2F tokens have no users
attribute.
Example Response
{
"response": [{
"date_added": 1446738417,
"registration_id": "D2GIWFX1X1XXD1D6IP2W5"
}],
"stat": "OK"
}
{
}
Returns a list of WebAuthn credentials associated with the user with ID user_id
.
GET /admin/v1/users/[user_id]/webauthncredentials
Parameters
None.
Query Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
404 |
No user was found with the given user_id .
|
Response Format
Key | Value |
---|---|
credential_name
|
Free-form label for the WebAuthn credential. |
date_added
|
The date the WebAuthn credential was registered in Duo. |
label
|
Indicates the type of WebAuthn credential. One of: “Security Key” or “Touch ID”. |
webauthnkey
|
The WebAuthn credential's registration identifier. |
Example Response
{
"response": [{
"credential_name": "YubiKey",
"date_added": 1550674764,
"label": "Security Key",
"webauthnkey": "WA4ED9AUVMSWUF00KES4"
}],
"stat": "OK"
}
Initiate a sync for the user specified by username
against the directory specified by the directory_key
. The directory_key
for a directory can be found by navigating to Users → Directory Sync in the Duo Admin Panel, and then clicking on the configured directory. Learn more about syncing individual users.
POST /admin/v1/users/directorysync/[directory_key]/syncuser
Parameters
Parameter | Required? | Description |
---|---|---|
username
|
Required | The user to update via directory sync. This should be the same as the user's username in the source directory. |
Response Codes
Response | Meaning |
---|---|
200 | The user was synced successfully. The user object is also returned (see Retrieve Users). |
404 |
The specified username or directory_key was incorrect, or the user is not managed by the specified directory.
|
429 | Too many requests; try again later. |
Response Format
Same as Retrieve Users.
Example Response
Same as Retrieve User by ID.
See Retrieve Groups by User ID, Associate Group with User, and Disassociate Group from User.
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.
GET /admin/v1/groups
Parameters
Paging Parameter | Required? | Description |
---|---|---|
limit
|
Optional |
The maximum number of records returned. Default: 100; Max: 100 |
offset
|
Optional |
The offset from 0 at which to start record retrieval. When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: 0 |
Query Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
Response Format
Key | Value | ||||||||
---|---|---|---|---|---|---|---|---|---|
desc
|
The group’s description. | ||||||||
push_enabled
|
If true, users in the group will be able to use Duo Push to authenticate. If false, users in the group will not be able to use Duo Push to authenticate. Note that this setting has no effect if Duo Push is disabled globally. | ||||||||
sms_enabled
|
If true, users in the group will be able to use SMS passcodes to authenticate. If false, users in the group will not be able to use SMS passcodes to authenticate. Note that this setting has no effect if SMS passcodes are disabled globally. | ||||||||
voice_enabled
|
If true, users in the group will be able to authenticate with a voice callback. If false, users in the group will not be able to authenticate with a voice callback. Note that this setting has no effect if voice callback is disabled globally. | ||||||||
mobile_otp_enabled
|
If true, users in the group will be able to authenticate with a passcode generated by Duo Mobile. If false, users in the group will not be able to authenticate with a passcode generated by Duo Mobile. Note that this setting has no effect if Duo Mobile passcodes are disabled globally. | ||||||||
group_id
|
The group’s ID. | ||||||||
name
|
The group’s name. | ||||||||
status
|
The group’s authentication status. May be one of:
|
Example Response
{
"response": [{
"desc": "This is group A",
"group_id": "DGXXXXXXXXXXXXXXXXXX",
"name": "Group A",
"push_enabled": true,
"sms_enabled": true,
"status": "active",
"voice_enabled": true,
"mobile_otp_enabled": true
},
{
"desc": "This is group B",
"group_id": "DGXXXXXXXXXXXXXXXXXX",
"name": "Group B",
"push_enabled": true,
"sms_enabled": true,
"status": "active",
"voice_enabled": true,
"mobile_otp_enabled": true
}],
"stat": "OK"
}
Create a new group.
POST /admin/v1/groups
Parameters
Parameter | Required? | Description |
---|---|---|
name | Required | The name of the group. |
desc | Optional | The description of the group. |
push_enabled | Optional | If true, users in the group will be able to use Duo Push to authenticate. If false, users in the group will not be able to use Duo Push to authenticate. Note that this setting has no effect if Duo Push is disabled globally. |
sms_enabled | Optional | If true, users in the group will be able to use SMS passcodes to authenticate. If false, users in the group will not be able to use SMS passcodes to authenticate. Note that this setting has no effect if SMS passcodes are disabled globally. |
voice_enabled | Optional | If true, users in the group will be able to authenticate with a voice callback. If false, users in the group will not be able to authenticate with a voice callback. Note that this setting has no effect if voice callback is disabled globally. |
mobile_otp_enabled | Optional | If true, users in the group will be able to authenticate with a passcode generated by Duo Mobile. If false, users in the group will not be able to authenticate with a passcode generated by Duo Mobile. Note that this setting has no effect if Duo Mobile passcodes are disabled globally. |
status | Optional | The authentication status of the group. See Retrieve Groups for a list of possible values. |
Response Codes
Response | Meaning |
---|---|
200 | Success. |
400 | Group with given name already exists or one of the parameters is invalid. |
Response Format
Key | Value |
---|---|
desc
|
The group’s description. |
push_enabled
|
If true, users in the group will be able to use Duo Push to authenticate. If false, users in the group will not be able to use Duo Push to authenticate. Note that this setting has no effect if Duo Push is disabled globally. |
sms_enabled
|
If true, users in the group will be able to use SMS passcodes to authenticate. If false, users in the group will not be able to use SMS passcodes to authenticate. Note that this setting has no effect if SMS passcodes are disabled globally. |
voice_enabled
|
If true, users in the group will be able to authenticate with a voice callback. If false, users in the group will not be able to authenticate with a voice callback. Note that this setting has no effect if voice callback is disabled globally. |
mobile_otp_enabled
|
If true, users in the group will be able to authenticate with a passcode generated by Duo Mobile. If false, users in the group will not be able to authenticate with a passcode generated by Duo Mobile. Note that this setting has no effect if Duo Mobile passcodes are disabled globally. |
group_id
|
The group’s ID. |
name
|
The group’s name. |
status
|
The group’s authentication status. See Retrieve Groups for a list of possible values. |
Example Response
{
"response": {
"desc": "This is an example group",
"group_id": "DGXXXXXXXXXXXXXXXXXX",
"mobile_otp_enabled": true,
"name": "Example Group",
"push_enabled": true,
"sms_enabled": false,
"status": "active",
"voice_enabled": true
},
"stat": "OK"
}
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
.
GET /admin/v2/groups/[group_id]
Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
404 | Group with given ID was not found. |
Response Format
Key | Value |
---|---|
desc
|
The group’s description. |
push_enabled
|
If true, users in the group will be able to use Duo Push to authenticate. If false, users in the group will not be able to use Duo Push to authenticate. Note that this setting has no effect if Duo Push is disabled globally. |
sms_enabled
|
If true, users in the group will be able to use SMS passcodes to authenticate. If false, users in the group will not be able to use SMS passcodes to authenticate. Note that this setting has no effect if SMS passcodes are disabled globally. |
voice_enabled
|
If true, users in the group will be able to authenticate with a voice callback. If false, users in the group will not be able to authenticate with a voice callback. Note that this setting has no effect if voice callback is disabled globally. |
mobile_otp_enabled
|
If true, users in the group will be able to authenticate with a passcode generated by Duo Mobile. If false, users in the group will not be able to authenticate with a passcode generated by Duo Mobile. Note that this setting has no effect if Duo Mobile passcodes are disabled globally. |
group_id
|
The group’s ID. |
name
|
The group’s name. |
status
|
The group’s authentication status. See Retrieve Groups for a list of possible values. |
Example Response
{
"response": {
"desc": "Group description",
"group_id": "DGXXXXXXXXXXXXXXXXXX",
"name": "Group Name",
"push_enabled": true,
"sms_enabled": true,
"status": "active",
"voice_enabled": true,
"mobile_otp_enabled": true
},
"stat": "OK"
}
Returns a paged list of members of a specified group. To fetch all results, call repeatedly with the offset parameter as long as the result metadata has a next_offset
value.
GET /admin/v2/groups/[group_id]/users
Parameters
Paging Parameter | Required? | Description |
---|---|---|
limit
|
Optional |
The maximum number of records returned. Default: 100; Max: 500 |
offset
|
Optional |
The offset from 0 at which to start record retrieval. When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: 0 |
Response Codes
Response | Meaning |
---|---|
200 | Success. |
400 | Invalid parameters. |
404 | Group with given ID was not found. |
Response Format
Key | Value |
---|---|
user_id
|
The user’s ID. |
username
|
The user’s username. |
Example Response
{
"metadata": {
"total_objects": 4
},
"response": [{
{
"user_id": "DUXXXXXXXXXXXXXXXXXX",
"username": "user1"
},
{
"user_id": "DUXXXXXXXXXXXXXXXXXX",
"username": "user2"
},
{
"user_id": "DUXXXXXXXXXXXXXXXXXX",
"username": "user3"
},
],
"stat": "OK"
}
The v1 groups endpoint limits the response to the first 4,000 group members. Consider migrating to the v2 endpoint.
GET /admin/v1/groups/[group_id]
Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
404 | Group with given ID was not found. |
Response Format
Key | Value |
---|---|
desc
|
The group’s description. |
push_enabled
|
If true, users in the group will be able to use Duo Push to authenticate. If false, users in the group will not be able to use Duo Push to authenticate. Note that this setting has no effect if Duo Push is disabled globally. |
sms_enabled
|
If true, users in the group will be able to use SMS passcodes to authenticate. If false, users in the group will not be able to use SMS passcodes to authenticate. Note that this setting has no effect if SMS passcodes are disabled globally. |
voice_enabled
|
If true, users in the group will be able to authenticate with a voice callback. If false, users in the group will not be able to authenticate with a voice callback. Note that this setting has no effect if voice callback is disabled globally. |
mobile_otp_enabled
|
If true, users in the group will be able to authenticate with a passcode generated by Duo Mobile. If false, users in the group will not be able to authenticate with a passcode generated by Duo Mobile. Note that this setting has no effect if Duo Mobile passcodes are disabled globally. |
group_id
|
The group’s ID. |
name
|
The group’s name. |
status
|
The group’s authentication status. See Retrieve Groups for a list of possible values. |
users
|
A list of the users in the group. |
Example Response
{
"response": {
"desc": "Group description",
"group_id": "DGXXXXXXXXXXXXXXXXXX",
"name": "Group Name",
"push_enabled": true,
"sms_enabled": true,
"status": "active",
"users": [{
"user_id": "DUXXXXXXXXXXXXXXXXXX",
"username": "User A"
},
{
"user_id": "DUXXXXXXXXXXXXXXXXXX",
"username": "User B"
}],
"voice_enabled": true,
"mobile_otp_enabled": true
},
"stat": "OK"
}
Update information about a group.
POST /admin/v1/groups/[group_id]
Parameters
Parameter | Required? | Description |
---|---|---|
name | Optional | Update the name of the group. |
desc | Optional | Update the description of the group. |
push_enabled | Optional | If true, users in the group will be able to use Duo Push to authenticate. If false, users in the group will not be able to use Duo Push to authenticate. Note that this setting has no effect if Duo Push is disabled globally. |
sms_enabled | Optional | If true, users in the group will be able to use SMS passcodes to authenticate. If false, users in the group will not be able to use SMS passcodes to authenticate. Note that this setting has no effect if SMS passcodes are disabled globally. |
voice_enabled | Optional | If true, users in the group will be able to use authenticate with a voice callback. If false, users in the group will not be able to authenticate with a voice callback. Note that this setting has no effect if voice callback is disabled globally. |
mobile_otp_enabled | Optional | If true, users in the group will be able to authenticate with a passcode generated by Duo Mobile. If false, users in the group will not be able to authenticate with a passcode generated by Duo Mobile. Note that this setting has no effect if Duo Mobile passcodes are disabled globally. |
status | Optional | The authentication status of the group. See Retrieve Groups for a list of possible values. |
Response Codes
Response | Meaning |
---|---|
200 | Success. |
400 | Invalid parameters. |
404 | Group with given ID was not found. |
Response Format
Key | Value |
---|---|
desc
|
The group’s updated description. |
push_enabled
|
If true, users in the group will be able to use Duo Push to authenticate. If false, users in the group will not be able to use Duo Push to authenticate. Note that this setting has no effect if Duo Push is disabled globally. |
sms_enabled
|
If true, users in the group will be able to use SMS passcodes to authenticate. If false, users in the group will not be able to use SMS passcodes to authenticate. Note that this setting has no effect if SMS passcodes are disabled globally. |
voice_enabled
|
If true, users in the group will be able to authenticate with a voice callback. If false, users in the group will not be able to authenticate with a voice callback. Note that this setting has no effect if voice callback is disabled globally. |
mobile_otp_enabled
|
If true, users in the group will be able to authenticate with a passcode generated by Duo Mobile. If false, users in the group will not be able to authenticate with a passcode generated by Duo Mobile. Note that this setting has no effect if Duo Mobile passcodes are disabled globally. |
group_id
|
The group’s ID. |
name
|
The group’s updated name. |
status
|
The group’s updated authentication status. See Retrieve Groups for a list of possible values. |
Example Response
{
"response": {
"desc": "Group description",
"group_id": "DGXXXXXXXXXXXXXXXXXX",
"name": "Group Name",
"push_enabled": true,
"sms_enabled": true,
"status": "active",
"voice_enabled": true,
"mobile_otp_enabled": true
},
"stat": "OK"
}
Delete a group.
DELETE /admin/v1/groups/[group_id]
Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | The group was deleted or did not exist. |
Response Format
None.
Example Response
{
"response": "",
"stat": "OK"
}
See Retrieve Phones by User ID, Associate Phone with User, and Disassociate Phone from User.
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.
GET /admin/v1/phones
Parameters
Paging Parameter | Required? | Description |
---|---|---|
limit
|
Optional |
The maximum number of records returned. Default: 100; Max: 500 |
offset
|
Optional |
The offset from 0 at which to start record retrieval. When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: 0 |
Query Parameters
Parameter | Required? | Description |
---|---|---|
number
|
Optional | Specify a phone number to look up a single phone. |
extension
|
Optional | The extension, if necessary. |
Response Codes
Response | Meaning |
---|---|
200 | Success. |
400 | Invalid number. |
Response Format
Key | Value | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
activated
|
Has this phone been activated for Duo Mobile yet? Either “true” or “false”. |
||||||||||
capabilities
|
List of strings, each a factor that can be used with the device.
|
||||||||||
encrypted
|
The encryption status of an Android or iOS device file system. One of: “Encrypted”, “Unencrypted”, or “Unknown”. Blank for other platforms. This information is available to Duo Beyond and Duo Access plan customers. |
||||||||||
extension
|
An extension, if necessary. |
||||||||||
fingerprint
|
Whether an Android or iOS phone is configured for biometric verification. One of: “Configured”, “Disabled”, or “Unknown”. Blank for other platforms. This information is available to Duo Beyond and Duo Access plan customers. |
||||||||||
last_seen
|
The timestamp of the last contact between Duo's service and the activated Duo Mobile app installed on the phone. Blank if the device has never activated Duo Mobile or if the platform does not support it. |
||||||||||
model
|
The phone's model. |
||||||||||
name
|
Free-form label for the phone. |
||||||||||
number
|
The phone number. A phone with a smartphone platform but no number is a tablet. |
||||||||||
phone_id
|
The phone’s ID. |
||||||||||
platform
|
The phone platform. One of: “unknown”, “google android”, “apple ios”, “windows phone 7”, “rim blackberry”, “java j2me”, “palm webos”, “symbian os”, “windows mobile”, or “generic smartphone”. “windows phone” is accepted as a synonym for “windows phone 7”. This includes devices running Windows Phone 8. If a smartphone’s exact platform is unknown but it will have Duo Mobile installed, use “generic smartphone” and generate an activation code. When the phone is activated its platform will be automatically detected. |
||||||||||
postdelay
|
The time (in seconds) to wait after the extension is dialed and before the speaking the prompt. |
||||||||||
predelay
|
The time (in seconds) to wait after the number picks up and before dialing the extension. |
||||||||||
screenlock
|
Whether screen lock is enabled on an Android or iOS phone. One of: “Locked”, “Unlocked”, or “Unknown”. Blank for other platforms. This information is available to Duo Beyond and Duo Access plan customers. |
||||||||||
sms_passcodes_sent
|
Have SMS passcodes been sent to this phone? Either “true” or “false”. |
||||||||||
tampered
|
Whether an iOS or Android device is jailbroken or rooted. One of: “Not Tampered”, “Tampered”, or “Unknown”. Blank for other platforms. This information is available to Duo Beyond and Duo Access plan customers. |
||||||||||
type
|
The type of phone. One of: “unknown”, “mobile”, or “landline”. |
||||||||||
users
|
A list of users associated with this phone. |
Example Response
{
"stat": "OK",
"response": [{
"activated": true,
"capabilities": [
"push",
"sms",
"phone",
"mobile_otp"
],
"encrypted": "Encrypted",
"extension": "",
"fingerprint": "Configured",
"last_seen": "2019-03-04T15:04:04",
"model": "Google Pixel 2 Xl",
"name": "",
"number": "+15555550100",
"phone_id": "DPFZRS9FB0D46QFTM899",
"platform": "Google Android",
"postdelay": "",
"predelay": "",
"screenlock": "Locked",
"sms_passcodes_sent": false,
"tampered": "Not tampered",
"type": "Mobile",
"users": [{
"alias1": "joe.smith",
"alias2": "jsmith@example.com"
"alias3": null,
"alias4": null,
"created": 1509717442,
"email": "jsmith@example.com",
"firstname": "Joe",
"is_enrolled": false,
"last_directory_sync": null,
"last_login": 1474399627,
"lastname": "Smith",
"notes": "",
"realname": "Joe Smith",
"status": "active",
"user_id": "DUJZ2U4L80HT45MQ4EOQ",
"username": "jsmith",
}]
}]
}
Create a new phone with a specified phone number or other parameters.
POST /admin/v1/phones
Parameters
Parameter | Required? | Description |
---|---|---|
number
|
Optional | The phone number. A phone with a smartphone platform but no number is a tablet. |
name
|
Optional | Free-form label for the phone. |
extension
|
Optional | The extension. |
type
|
Optional | The phone type. See Retrieve Phones for a list of possible values. |
platform
|
Optional | The phone platform. See Retrieve Phones for a list of possible values. |
predelay
|
Optional | The time (in seconds) to wait after the number picks up and before dialing the extension. |
postdelay
|
Optional | The time (in seconds) to wait after the extension is dialed and before the speaking the prompt. |
Response Codes
Response | Meaning |
---|---|
200 | The phone was created successfully. The newly created phone is also returned (see Retrieve Phones). |
400 |
Invalid or missing parameter(s), or phone already exists with the given number and extension .
|
Response Format
Same as Retrieve Phone by ID.
Example Response
Same as Retrieve Phone by ID.
Return the single phone with phone_id
.
GET /admin/v1/phones/[phone_id]
Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
404 |
No phone was found with the given phone_id .
|
Response Format
Same as Retrieve Phones.
Example Response
{
"stat": "OK",
"response": [{
"activated": true,
"capabilities": [
"push",
"sms",
"phone",
"mobile_otp"
],
"encrypted": "Encrypted",
"extension": "",
"fingerprint": "Configured",
"last_seen": "2019-03-04T15:04:04",
"model": "Google Pixel 2 Xl",
"name": "",
"number": "+15555550100",
"phone_id": "DPFZRS9FB0D46QFTM899",
"platform": "Google Android",
"postdelay": "",
"predelay": "",
"screenlock": "Locked",
"sms_passcodes_sent": false,
"tampered": "Not tampered",
"type": "Mobile",
"users": [{
"alias1": "joe.smith",
"alias2": "jsmith@example.com"
"alias3": null,
"alias4": null,
"created": 1509717442,
"email": "jsmith@example.com",
"firstname": "Joe",
"is_enrolled": false,
"last_directory_sync": null,
"last_login": 1474399627,
"lastname": "Smith",
"notes": "",
"realname": "Joe Smith",
"status": "active",
"user_id": "DUJZ2U4L80HT45MQ4EOQ",
"username": "jsmith",
}]
}]
}
Change the details of the phone with ID phone_id
.
POST /admin/v1/phones/[phone_id]
Parameters
Parameter | Required? | Description |
---|---|---|
number
|
Optional | The new number. |
name
|
Optional | Free-form label for the phone. |
extension
|
Optional | The new extension. |
type
|
Optional | The phone type. See Retrieve Phones for a list of possible values. |
platform
|
Optional | The phone platform. See Retrieve Phones for a list of possible values. |
predelay
|
Optional | The time (in seconds) to wait after the number picks up and before dialing the extension. |
postdelay
|
Optional | The time (in seconds) to wait after the extension is dialed and before the speaking the prompt. |
Response Codes
Response | Meaning |
---|---|
200 | The phone was modified successfully. The phone object is returned. |
400 |
Invalid or missing parameter(s), or phone already exists with the given number and extension .
|
404 |
No phone was found with the given phone_id .
|
Response Format
Same as Retrieve Phone by ID.
Example Response
Same as Retrieve Phone by ID.
Delete the phone with ID phone_id
from the system.
DELETE /admin/v1/phones/[phone_id]
Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | The phone was deleted or did not exist. |
Response Format
Empty string.
Example Response
{
"stat": "OK",
"response": ""
}
Generate a Duo Mobile activation code. This method will fail if the phone’s type or platform are Unknown.
POST /admin/v1/phones/[phone_id]/activation_url
Parameters
Parameter | Required? | Description |
---|---|---|
valid_secs
|
Optional | The number of seconds this activation code should be valid for. Default: 86400 (one day). |
install
|
Optional | “1” to also return an installation URL for Duo Mobile; “0” to not return. Default: “0”. |
Response Codes
Response | Meaning |
---|---|
200 | The activation code was successfully generated. |
400 | Invalid parameters or invalid phone. The phone’s platform must be one on which Duo Mobile can be activated. |
404 |
No phone was found with the given phone_id .
|
Response Format
Key | Value |
---|---|
activation_url
|
Opening this URL with the Duo Mobile app will complete activation. |
activation_barcode
|
URL of an image. Scan the image with Duo Mobile to complete activation.
This barcode uses the same activation code as activation_url .
|
installation_url
|
Opening this URL on the phone will prompt the user to install Duo Mobile. Only present if install was “1”.
|
valid_secs
|
The number of seconds that the activation code is valid for. |
Example Response
{
"stat": "OK",
"response": {
"activation_barcode": "https://api-abcdef.duosecurity.com/frame/qr?value=duo%3A%2F%2Factivation-code",
"activation_url": "https://m-abcdef.duosecurity.com/iphone/7dmi4Oowz5g3J47FARLs",
"valid_secs": 3600
}
}
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.
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 should be valid for. Default: 86400 (one day). |
install
|
Optional | “1” to cause an installation SMS message to be sent before the activation message, “0” to not send an installation SMS message. Default: “0”. |
installation_msg
|
Optional | A custom installation message to send to the user. Only valid if installation was requested. Must contain the phrase “<insturl>”, which is replaced with the installation URL. |
activation_msg
|
Optional | A custom activation message to send to the user. Must contain “<acturl>”, which is replaced with the activation URL. |
Response Codes
Response | Meaning |
---|---|
200 | The activation code was generated and sent successfully. |
400 | Invalid parameters or invalid phone. The phone must be able to receive SMS messages and its platform must be one on which Duo Mobile can be activated. |
404 |
No phone was found with the given phone_id .
|
500 | Failed to send SMS message or SMS message too long. |
Response Format
Key | Value |
---|---|
activation_msg
|
The text of the activation message. |
activation_barcode
|
URL of an image. Scan the image with Duo Mobile to complete activation.
This barcode contains the same activation code as activation_url .
|
installation_msg
|
The text of the installation message. Only present if the install parameter was set to 1 in the request.
|
valid_secs
|
The number of seconds that the activation URL is valid for. |
Example Response
{
"stat": "OK",
"response": {
"activation_barcode": "https://api-abcdef/frame/qr\?*value=duo%3A%2F%2FXoudqt8a9F-Jqt",
"activation_msg": "To activate the Duo Mobile app, click this link: https://m-eval.duosecurity.com/iphone/7dmi4Oowz5g3J47FARLs",
"installation_msg": "Welcome to Duo! To install the Duo Mobile app, click this link: http://m-eval.duosecurity.com",
"valid_secs": 3600
}
}
Send a message via SMS describing how to install Duo Mobile. This method will fail if the phone’s type or platform are Unknown.
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"
}
}
Generate a new batch of SMS passcodes send them to the phone in a single SMS message.
POST /admin/v1/phones/[phone_id]/send_sms_passcodes
Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | The passcodes were generated and sent successfully. |
404 |
No phone was found with the given phone_id .
|
Response Format
Empty string.
Example Response
{
"stat": "OK",
"response": ""
}
See Retrieve Hardware Tokens by User ID, Associate Hardware Token with User, and Disassociate Hardware Token from User.
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.
GET /admin/v1/tokens
Parameters
Paging Parameter | Required? | Description |
---|---|---|
limit
|
Optional |
The maximum number of records returned. Default: 100; Max: 500 |
offset
|
Optional |
The offset from 0 at which to start record retrieval. When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: 0 |
Query Parameters
Parameter | Required? | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
type
|
Optional* |
Specify a type and serial number to look up a single hardware token. One of:
* 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 |
---|---|
token_id
|
The hardware token’s unique ID. |
type
|
The type of hardware token. |
serial
|
The serial number of the hardware token, used to uniquely identify
the hardware token when paired with type .
|
totp_step
|
Null for all supported token types. |
users
|
A list of users that this hardware token is associated with. |
Example Response
{
"stat": "OK",
"response": [{
"serial": "0",
"token_id": "DHIZ34ALBA2445ND4AI2",
"type": "d1",
"totp_step": null,
"users": [{
"user_id": "DUJZ2U4L80HT45MQ4EOQ",
"username": "jsmith",
"alias1": "joe.smith",
"alias2": "jsmith@example.com",
"realname": "Joe Smith",
"email": "jsmith@example.com",
"status": "active",
"last_login": 1343921403,
"notes": ""
}]
}]
}
Create a new hardware token.
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. Default: 0. This parameter is only valid for HOTP-6 and HOTP-8 hardware tokens. | ||||||||
private_id
|
Optional | The YubiKey private ID. This parameter is required for YubiKey hardware tokens. | ||||||||
aes_key
|
Optional | The YubiKey AES key. This parameter is required for YubiKey hardware tokens. |
Response Codes
Response | Meaning |
---|---|
200 | The hardware token was created successfully. The newly created hardware token is also returned (see Retrieve Hardware Tokens). |
400 |
Invalid or missing parameter(s), or hardware token already exists with the given type and serial .
|
Response Format
Same as Retrieve Hardware Tokens.
Example Response
Same as Retrieve Hardware Token by ID.
Return the single hardware token with token_id
.
GET /admin/v1/tokens/[token_id]
Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
404 |
No hardware token was found with the given token_id .
|
Response Format
Same as Retrieve Hardware Tokens.
Example Response
{
"stat": "OK",
"response": {
"serial": "0",
"token_id": "DHIZ34ALBA2445ND4AI2",
"type": "d1",
"totp_step": null,
"users": [{
"user_id": "DUJZ2U4L80HT45MQ4EOQ",
"username": "jsmith",
"alias1": "joe.smith",
"alias2": "jsmith@example.com",
"realname": "Joe Smith",
"email": "jsmith@example.com",
"status": "active",
"last_login": 1343921403,
"notes": ""
}]
}
}
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.
POST /admin/v1/tokens/[token_id]/resync
Parameters
Parameter | Required? | Description |
---|---|---|
code1
|
Required | The first code from the token. |
code2
|
Required | The first code from the token. |
code3
|
Required | The first code from the token. |
Response Codes
Response | Meaning |
---|---|
200 | The token was resynced successfully. |
400 | Invalid or missing parameter(s) or cannot resynchronize tokens of this type. |
404 |
No token was found with the given token_id .
|
Response Format
Empty string.
Example Response
{
"stat": "OK",
"response": ""
}
Delete the hardware token with ID token_id
from the system.
DELETE /admin/v1/tokens/[token_id]
Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | The token was deleted or did not exist. |
Response Format
Empty string.
Example Response
{
"stat": "OK",
"response": ""
}
See Retrieve U2F Tokens by User ID.
Returns a paged list of all registered U2F tokens. To fetch all results, call repeatedly with the offset parameter as long as the result metadata has a next_offset
value.
GET /admin/v1/u2ftokens
Parameters
Paging Parameter | Required? | Description |
---|---|---|
limit
|
Optional |
The maximum number of records returned. Default: 100; Max: 500 |
offset
|
Optional |
The offset from 0 at which to start record retrieval. When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: 0 |
Response Codes
Response | Meaning |
---|---|
200 | Success. Returns a list of U2F tokens. |
Response Format
Key | Value | ||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
date_added
|
The date the U2F token was registered in Duo. | ||||||||||||||||||||||||||||||||||||||
registration_id
|
The U2F token's registration identifier. Use with GET token by ID. | ||||||||||||||||||||||||||||||||||||||
user
|
Selected information about the user attached to the U2F token.
|
Example Response
{
"stat": "OK",
"response": [{
"date_added": 1444678994,
"registration_id": "D21RU6X1B1DF5P54B6PV",
"user": {
"alias1": "joe.smith",
"alias2": "jsmith@example.com",
"alias3": null,
"alias4": null,
"created": 1384275337,
"email": "jsmith@example.com",
"firstname": Joe,
"is_enrolled": true,
"last_directory_sync": 1384275337,
"last_login": 1514922986,
"lastname": Smith,
"notes": "",
"realname": "Joe Smith",
"status": "active",
"user_id": "DU3RP9I2WOC59VZX672N",
"username": "jsmith",
}]
}]
}
Return the single U2F token with registration_id
.
GET /admin/v1/u2ftokens/[registration_id]
Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
404 |
No U2F token was found with the given registration_id .
|
Response Format
Same as Retrieve U2F Tokens.
Example Response
{
"stat": "OK",
"response": [{
"date_added": 1444678994,
"registration_id": "D21RU6X1B1DF5P54B6PV",
"user": {
"alias1": "joe.smith",
"alias2": "jsmith@example.com",
"alias3": null,
"alias4": null,
"created": 1384275337,
"email": "jsmith@example.com",
"firstname": Joe,
"is_enrolled": true,
"last_directory_sync": 1384275337,
"last_login": 1514922986,
"lastname": Smith,
"notes": "",
"realname": "Joe Smith",
"status": "active",
"user_id": "DU3RP9I2WOC59VZX672N",
"username": "jsmith",
}]
}]
}
Delete the U2F token with ID registration_id
from the system.
DELETE /admin/v1/u2ftokens/[registration_id]
Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | The U2F token was deleted or did not exist. |
Response Format
Empty string.
Example Response
{
"stat": "OK",
"response": ""
}
See Create Bypass Codes for User and Retrieve Bypass Codes by User ID.
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.
GET /admin/v1/bypass_codes
Parameters
Paging Parameter | Required? | Description |
---|---|---|
limit
|
Optional |
The maximum number of records returned. Default: 100; Max: 500 |
offset
|
Optional |
The offset from 0 at which to start record retrieval. When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: 0 |
Response Codes
Response | Meaning |
---|---|
200 | Success. Returns metadata information for all bypass codes. |
Response Format
Key | Value | ||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
admin_email
|
The email address of the Duo administrator who created the bypass code. | ||||||||||||||||||||||||||||||||||||||
bypass_code_id
|
The bypass code's identifier. | ||||||||||||||||||||||||||||||||||||||
created
|
The bypass code creation date timestamp. | ||||||||||||||||||||||||||||||||||||||
expiration
|
The expiration timestamp of the bypass code, or "null" if the bypass code does not expire on a certain date. | ||||||||||||||||||||||||||||||||||||||
reuse_count
|
The number of times the bypass code may be used before expiring, or "null" if the bypass code has no limit on the number of times it may be used. | ||||||||||||||||||||||||||||||||||||||
user
|
Selected information about the user attached to the bypass code.
|
Example Response
{
"stat": "OK",
"response": [{
"bypass_code_id": "DB2A9F0012RL54001FA3",
"created": 1522260759,
"expiration": 1522264359,
"reuse_count": 1,
"user": {
"alias1": "joe.smith",
"alias2": "jsmith@example.com",
"alias3": null,
"alias4": null,
"created": 1384275337,
"email": "jsmith@example.com",
"firstname": Joe,
"is_enrolled": true,
"last_directory_sync": 1384275337,
"last_login": 1514922986,
"lastname": Smith,
"notes": "",
"realname": "Joe Smith",
"status": "active",
"user_id": "DU3RP9I2WOC59VZX672N",
"username": "jsmith"
}]
}]
}
Return information about a single bypass code with bypass_code_id
. Output does not include the actual bypass code.
GET /admin/v1/bypass_codes/[bypass_code_id]
Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
404 |
No bypass code was found with the given bypass_code_id .
|
Response Format
Same as Retrieve Bypass Codes.
Example Response
{
"stat": "OK",
"response": [{
"bypass_code_id": "DB2A9F0012RL54001FA3",
"created": 1522260759,
"expiration": 1522264359,
"reuse_count": 1,
"user": {
"alias1": "joe.smith",
"alias2": "jsmith@example.com",
"alias3": null,
"alias4": null,
"created": 1384275337,
"email": "jsmith@example.com",
"firstname": Joe,
"is_enrolled": true,
"last_directory_sync": 1384275337,
"last_login": 1514922986,
"lastname": Smith,
"notes": "",
"realname": "Joe Smith",
"status": "active",
"user_id": "DU3RP9I2WOC59VZX672N",
"username": "jsmith"
}]
}]
}
Delete the bypass code with ID bypass_code_id
from the system.
DELETE /admin/v1/bypass_codes/[bypass_code_id]
Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | The bypass code was deleted. |
404 |
No bypass code was found with the given bypass_code_id .
|
Response Format
Empty string.
Example Response
{
"stat": "OK",
"response": ""
}
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.
GET /admin/v1/integrations
Parameters
Paging Parameter | Required? | Description |
---|---|---|
limit
|
Optional |
The maximum number of records returned. Default: 100; Max: 500 |
offset
|
Optional |
The offset from 0 at which to start record retrieval. When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: 0 |
Response Codes
Response | Meaning |
---|---|
200 | Success. |
Response Format
Key | Value | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
enroll_policy
|
What to do after an unenrolled user passes primary authentication. One of:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
name
|
The integration’s name. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
notes
|
Description of the integration. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
secret_key
|
Secret used when configuring systems to use this integration. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
type
|
Integration type. One of
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
adminapi_admins
|
1 if the integration has been granted permission for Administrators methods; 0 otherwise. Only applicable to Admin API integrations. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
adminapi_info
|
1 if the integration has been granted permission for Account Info methods; 0 otherwise. Only applicable to Admin API integrations. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
adminapi_integrations
|
1 if the integration has been granted permission for Integrations methods; 0 otherwise. Only applicable to Admin API integrations. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
adminapi_read_log
|
1 if the integration has been granted permission for Logs methods; 0 otherwise. Only applicable to Admin API integrations. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
adminapi_read_resource
|
1 if the integration has been granted permission to retrieve objects like users, phones, and hardware tokens; 0 otherwise. Only applicable to Admin API integrations. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
adminapi_settings
|
1 if the integration has been granted permission for Settings methods; 0 otherwise. Only applicable to Admin API integrations. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
adminapi_write_resource
|
1 if the integration has been granted permission to modify objects like users, phones, and hardware tokens; 0 otherwise. Only applicable to Admin API integrations. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
trusted_device_days
|
Number of days to allow a user to skip second factor login. Must be between 0 and 60; 0 disables this option. Supported on the following integrations:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ip_whitelist
|
CSV string of IPs/Ranges from which the second authentication factor will not be required, will be returned as an array. Example: “192.0.2.8,198.51.100.0-198.51.100.20,203.0.113.0/24”. Supported with these integration types:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ip_whitelist_enroll_policy
|
Policy for handling new users from IPs on the whitelist. One of:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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": 1,
"adminapi_info": 1,
"adminapi_integrations": 1,
"adminapi_read_log": 1,
"adminapi_read_resource": 1,
"adminapi_settings": 1,
"adminapi_write_resource": 1,
"enroll_policy": "enroll",
"greeting": "Welcome to Duo.",
"groups_allowed": [],
"integration_key": "DIRWIH0ZZPV4G88B37VQ",
"ip_whitelist": [
"192.0.2.8",
"198.51.100.0-198.51.100.20",
"203.0.113.0/24"
],
"ip_whitelist_enroll_policy": "enforce",
"name": "Web Application",
"notes": "",
"secret_key": "QO4ZLqQVRIOZYkHfdPDORfcNf8LeXIbCWwHazY7",
"self_service_allowed": false,
"trusted_device_days": 0,
"type": "websdk",
"username_normalization_policy": "None",
"visual_style": "default"
}
}
Create a new integration. The new integration key and secret key are randomly generated and returned in the response.
POST /admin/v1/integrations
Parameters
Parameter | Required? | Description |
---|---|---|
name
|
Required | The name of the integration to create. |
type
|
Required | The type of the integration to create. Refer to Retrieve Integrations for a list of valid values. Note that integrations of type “azure-ca” may not be created via the API. |
enroll_policy
|
Optional | What to do after an unenrolled user passes primary authentication. Refer to Retrieve Integrations for a list of valid values. |
greeting
|
Optional | Voice greeting read before the authentication instructions to users who authenticate with a phone callback. |
groups_allowed
|
Optional |
A comma-separated list of group IDs that are allowed to authenticate with the integration. If empty, all groups are allowed.
Object limits: 100 groups per integration. |
notes
|
Optional | Description of the integration. |
adminapi_admins
|
Optional | Set to 1 to grant an Admin API integration permission for all Admins methods. Defaults to 0. |
adminapi_info
|
Optional | If creating an Admin API integration, set this to 1 to grant it permission for all Account Info methods. Defaults to 0. |
adminapi_integrations
|
Optional | Set to 1 to grant an Admin API integration permission for all Integrations methods. Defaults to 0. |
adminapi_read_log
|
Optional | Set to 1 to grant an Admin API integration permission for all Logs methods. Defaults to 0. |
adminapi_read_resource
|
Optional | Set to 1 to grant an Admin API integration permission to retrieve objects like users, phones, and hardware tokens. Defaults to 0. |
adminapi_settings
|
Optional | Set to 1 to grant an Admin API integration permission for all Settings methods. Defaults to 0. |
adminapi_write_resource
|
Optional | Set to 1 to grant an Admin API integration permission to create and modify objects like users, phones, and hardware tokens. Defaults to 0. |
trusted_device_days
|
Optional | Number of days to allow a user to trust the device they are logging in with. Refer to Retrieve Integrations for a list of supported integrations. |
ip_whitelist
|
Optional | CSV string of trusted IPs/Ranges. Refer to Retrieve Integrations for a list of supported integrations. |
ip_whitelist_enroll_policy
|
Optional | What to do after a new user from a trusted IP completes primary authentication. Refer to Retrieve Integrations for a list of valid values. |
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. |
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. |
Response Codes
Response | Meaning |
---|---|
200 | Success. Returns the newly created integration. |
400 |
Invalid or missing parameters, one-to-many object limit reached, or integration already exists with the given name .
|
500 | Other internal error. |
Response Format
Same as Retrieve Integrations.
Example Response
Same as Retrieve Integration by Integration Key.
Return the single integration with integration_key
.
GET /admin/v1/integrations/[integration_key]
Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
404 |
No integration was found with the given integration_key .
|
Response Format
Same as Retrieve Integrations with some additional information.
Key | Value |
---|---|
policy_key
|
The identifying policy key for the custom policy attached to the integration. Not shown if no policy attached to the integration. |
Example Response
{
"stat": "OK",
"response": {
"adminapi_admins": 1,
"adminapi_info": 1,
"adminapi_integrations": 1,
"adminapi_read_log": 1,
"adminapi_read_resource": 1,
"adminapi_settings": 1,
"adminapi_write_resource": 1,
"enroll_policy": "enroll",
"greeting": "Welcome to Duo.",
"groups_allowed": [],
"integration_key": "DIRWIH0ZZPV4G88B37VQ",
"ip_whitelist": [],
"ip_whitelist_enroll_policy": "enforce",
"name": "Web Application",
"notes": "",
"policy_key": "POXXXXXXXXXXXXXXX98Y",
"secret_key": "QO4ZLqQVRIOZYkHfdPDORfcNf8LeXIbCWwHazY7",
"self_service_allowed": false,
"trusted_device_days": 0,
"type": "websdk",
"username_normalization_policy": "None",
"visual_style": "default"
}
}
Change the name, enrollment policy, greeting, and/or notes of the integration with integration key integration_key
, or reset its secret key. When modifying an Admin API integration permissions can also be added or removed.
POST /admin/v1/integrations/[integration_key]
Parameters
Parameter | Required? | Description |
---|---|---|
name
|
Optional | New name for the integration. |
enroll_policy
|
Optional | New policy for what to do after an unenrolled user passes primary authentication. Refer to Retrieve Integrations for a list of valid values. |
greeting
|
Optional | New voice greeting. Will be read before the authentication instructions to users who authenticate with a phone callback. |
groups_allowed
|
Optional |
A comma-separated list of group IDs that are allowed to authenticate with the integration. If set to an empty string, all groups will be allowed.
Object limits: 100 groups per integration. |
notes
|
Optional | New description of 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. |
adminapi_admins
|
Optional | Set to 1 to grant an Admin API integration permission for all Admins methods or 0 to remove access to them. |
adminapi_info
|
Optional | Set to 1 to grant an Admin API integration permission for all Account Info methods or 0 to remove access to them. |
adminapi_integrations
|
Optional | Set to 1 to grant an Admin API integration permission for all Integrations methods or 0 to remove access to them. |
adminapi_read_log
|
Optional | Set to 1 to grant an Admin API integration permission for all Logs methods or 0 to remove access to them. |
adminapi_read_resource
|
Optional | Set to 1 to grant an Admin API integration permission to retrieve objects like users, phones, and hardware tokens or 0 to remove access to them. |
adminapi_settings
|
Optional | Set to 1 to grant an Admin API integration permission for all Settings methods or 0 to remove access to them. |
adminapi_write_resource
|
Optional | Set to 1 to grant an Admin API integration permission to create and modify objects like users, phones, and hardware tokens or 0 to remove access to them. |
trusted_device_days
|
Optional | New number of days to allow a user to trust the device they are logging in with. Refer to Retrieve Integrations for a list of supported integrations. |
ip_whitelist
|
Optional | CSV string of trusted IPs/Ranges. Refer to Retrieve Integrations for a list of supported integrations. |
ip_whitelist_enroll_policy
|
Optional | New policy for what to do after a new user from a trusted IP completes primary authentication. Refer to Retrieve Integrations for a list of valid values. |
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. |
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. |
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. Leave the value blank to detach the currently attached policy from an integration. |
Response Codes
Response | Meaning |
---|---|
200 | The integration was modified successfully. The integration object is also returned (see Retrieve Integration by Integration Key). |
400 |
Invalid or missing parameters, one-to-many object limit reached, an integration already exists with the given name , or attempting to reset the secret key used to sign this API request.
|
404 |
No integration was found with the given integration_key .
|
500 | Other internal error. |
Response Format
Same as Retrieve Integrations.
Example Response
Same as Retrieve Integration by Integration Key.
Delete 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.
DELETE /admin/v1/integrations/[integration_key]
Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | The integration was deleted or did not exist. |
400 | Attempting to delete the integration whose secret key was used to sign this API request. |
Response Format
Empty string.
Example Response
{
"stat": "OK",
"response": ""
}
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.
GET /admin/v1/endpoints
Parameters
Paging Parameter | Required? | Description |
---|---|---|
limit
|
Optional |
The maximum number of records returned. Default: 100; Max: 500 |
offset
|
Optional |
The offset from 0 at which to start record retrieval. When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: 0 |
Response Codes
Response | Meaning |
---|---|
200 | Success. |
Response Format
Key | Value |
---|---|
browsers
|
Collected information about all detected browsers on an individual endpoint. |
browser_family
|
The web browser family. |
browser_version
|
The web browser version. |
flash_version
|
The Flash plugin version. If not present then “uninstalled”. |
java_version
|
The Java plugin version. If not present then “uninstalled”. |
last_used
|
The date and time that the endpoint's browser was last used for access, shown as a Unix timestamp. |
device_identifier
|
The unique attribute value that identifies the endpoint in the management system. Returned for Duo Beyond customers only. |
device_identifier_type
|
The management system attribute used to identify a unique endpoint. One of “hardware_uuid“, “fqdn“, “hardware_serial“, “device_udid“, or none. Returned for Duo Beyond customers only. |
device_username
|
The unique attribute value that identifies the endpoint's associated user in the management system. Returned for Duo Beyond customers only. |
device_username_type
|
The management system attribute used to identify the user associated with the unique endpoint. One of “os_username“, “upn“, “username“, “email“, or none. Returned for Duo Beyond customers only. |
email
|
The email address, if present, of the user associated with an endpoint. |
epkey
|
The endpoint’s unique identifier. |
model
|
The device model of a 2FA endpoint. |
os_family
|
The endpoint’s operating system platform. |
os_version
|
The endpoint’s operating system version. |
trusted_endpoint
|
Whether the endpoint is a Duo managed endpoint. One of “yes“, “no“, or “unknown“. Returned for Duo Beyond customers only. |
type
|
The endpoint’s device class. |
username
|
The Duo username of the user associated with an endpoint. |
Example Response
{
"stat": "OK",
"response": [{
"browsers": [{
"browser_family": "Chrome",
"browser_version": "51.0.2704.103",
"flash_version": "22.0.0.0",
"java_version": "uninstalled"
},
{
"browser_family": "Safari",
"browser_version": "9.1.1",
"flash_version": "uninstalled",
"java_version": "1.8.0.45",
"last_used": 1474483713
}],
"device_identifier": "3FA47335-1976-3BED-8286-D3F1ABCDEA13",
"device_identifier_type": "hardware_uuid",
"device_username": "mba22915\u00e2\u0080\u0099s MacBook Air/mba22915",
"device_username_type": "os_username",
"email": "ejennings@example.com",
"epkey": "EP18JX1A10AB102M2T2X",
"model": "",
"os_family": "Mac OS X",
"os_version": "10.11.5",
"trusted_endpoint": "yes",
"type": "",
"username": "ejennings"
},
{
"browsers": [{
{
"browser_family": "Mobile Safari",
"browser_version": "9.0",
"flash_version": "uninstalled",
"java_version": "uninstalled"
}],
"device_identifier": "",
"device_identifier_type": "",
"device_username": "",
"device_username_type": "",
"email": "",
"epkey": "EP65MWZWXA10AB1027TQ",
"model": "iPhone",
"os_family": "iOS",
"os_version": "9.3.3",
"trusted_endpoint": "unknown",
"type": "",
"username": "mhanson"
}],
"stat": "OK"
}
Return information for an individual endpoint with epkey
.
GET /admin/v1/endpoints/[epkey]
Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
404 |
No endpoint was found with the given epkey .
|
Response Format
Same as Retrieve Endpoints.
Example Response
{
"stat": "OK",
"response": [{
"browsers": [{
"browser_family": "Chrome",
"browser_version": "54.0.2840.27",
"flash_version": "23.0.0.173",
"java_version": "uninstalled",
"last_used": 1474483713
}],
"device_identifier": "3FA47335-1976-3BED-8286-D3F1ABCDEA13",
"device_identifier_type": "hardware_uuid",
"device_username": "mba22915\u00e2\u0080\u0099s MacBook Air/mba22915",
"device_username_type": "os_username",
"email": "amoss@example.com",
"epkey": "EP18JX1A10AB102M2T2X",
"model": "",
"os_family": "Mac OS X",
"os_version": "10.11.6",
"trusted_endpoint": "yes",
"type": "",
"username": "amoss"
}],
"stat": "OK"
}
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.
GET /admin/v1/admins
Parameters
Paging Parameter | Required? | Description |
---|---|---|
limit
|
Optional |
The maximum number of records returned. Default: 100; Max: 500 |
offset
|
Optional |
The offset from 0 at which to start record retrieval. When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: 0 |
Query Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
Response Format
Key | Value |
---|---|
admin_id
|
The administrator’s ID. |
email
|
The administrator’s email address. |
last_login
|
The last time this administrator logged in, as a UNIX timestamp, or “null” if the administrator has not logged in. |
name
|
The administrator’s full name. |
password_change_required
|
Either “true” if the administrator must change their password at the next login, or “false” if no password change is required. |
phone
|
The administrator’s phone number. |
restricted_by_admin_units
|
Is this administrator restricted by an administrative unit assignment? Either “true” or “false”. Must be set to “true” in order to add the admin to an administrative unit using the API. |
role
|
The administrator’s role. One of: “Owner”, “Administrator”, “Application Manager”, “User Manager”, “Help Desk”, “Billing”, “Phishing Manager”, or “Read-only”. Only present in the response if the customer edition includes the Administrative Roles feature. |
status
|
The administrator account's status. Either “Active” or “Disabled”. |
Example Response
{
"stat": "OK",
"response": {
"admin_id": "DEVKWVBJA7LO95OIBIS3",
"email": "rscott@example.com",
"last_login": 1343921403,
"name": "Rachael Scott",
"password_change_required": false,
"phone": "+17345551000",
"restricted_by_admin_units": false,
"role": "Owner",
"status": "Active"
}
}
Create a new administrator.
POST /admin/v1/admins
Parameters
Parameter | Required? | Description |
---|---|---|
email
|
Required | Valid email address for the new administrator. |
password
|
Required | Password for the new administrator. Must be at least twelve characters long. |
name
|
Required | Name for the new administrator. |
phone
|
Required | Phone number for the new administrator. |
password_change_required
|
Optional | Specify “true” to require that the admin pick a new password at their next login, or “false” if no password change is required. |
role
|
Optional |
The administrator’s role. One of: “Owner”, “Administrator”, “Application Manager”, “User Manager”, “Help Desk”, “Billing”, “Phishing Manager”, or “Read-only”. The role names are case-sensitive. Roles other than “Owner” are effective only if the customer edition includes the Administrative Roles feature. |
restricted_by_admin_units
|
Optional |
Is this administrator restricted by an administrative unit assignment? Either “true” or “false”. Defaults to “false” if not specified. Must be set to “true” in order to add the admin to an administrative unit using the API. |
status
|
Optional | The new administrator account's status. Either “Active” or “Disabled” (case-sensitive). |
Response Codes
Response | Meaning |
---|---|
200 | Success. Returns the newly created administrator. |
400 | Invalid or missing parameters, or the provided email address is already in use by another administrator. |
Response Format
Same as Retrieve Administrators.
Example Response
{
"stat": "OK",
"response": {
"admin_id": "DEVKWVBJA7LO95OIBIS3",
"email": "rscott@example.com",
"last_login": null,
"name": "Rachael Scott",
"password_change_required": false,
"phone": "+17345551000",
"restricted_by_admin_units": false,
"role": "Owner",
"status": "Active"
}
}
Return the single administrator with the administrator ID administrator_id
.
GET /admin/v1/admins/[administrator_id]
Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
404 |
No administrator was found with the given administrator_id .
|
Response Format
Same as Retrieve Administrators.
Example Response
{
"stat": "OK",
"response": {
"admin_id": "DEVKWVBJA7LO95OIBIS3",
"email": "rscott@example.com",
"last_login": 1343921403,
"name": "Rachael Scott",
"password_change_required": false,
"phone": "+17345551000",
"restricted_by_admin_units": false,
"role": "Owner",
"status": "Active"
}
}
Change the name, password, and/or phone number of the administrator with the administrator ID administrator_id
.
POST /admin/v1/admins/[administrator_id]
Parameters
Parameter | Required? | Description |
---|---|---|
name
|
Optional | New name for the administrator. |
phone
|
Optional | New phone number for the administrator. If this parameter is specified it cannot be empty. |
password
|
Optional | New password for the administrator. If this parameter is present it must be at least twelve characters. |
password_change_required
|
Optional | Specify “true” to require that the admin pick a new password at their next login, or “false” if no password change is required. |
role
|
Optional |
New role for the administrator. One of: “Owner”, “Administrator”, “Application Manager”, “User Manager”, “Help Desk”, “Billing”, “Phishing Manager”, or “Read-only”. The role names are case-sensitive. Roles other than “Owner” are effective only if the customer edition includes the Administrative Roles feature. |
restricted_by_admin_units
|
Optional |
Is this administrator restricted by an administrative unit assignment? Either “true” or “false”. Must be set to “true” in order to add the admin to an administrative unit using the API. |
status
|
Optional | The administrator account status. Either “Active” or “Disabled” (case-sensitive). |
Response Codes
Response | Meaning |
---|---|
200 | The administrator was modified successfully. The administrator object is also returned (see Retrieve Administrator by ID.). |
400 | Invalid or missing parameters. |
404 |
No administrator was found with the given administrator_id .
|
Response Format
Same as Retrieve Administrators.
Example Response
Same as Retrieve Administrator by ID.
Delete the administrator with administrator ID administrator_id
from the system.
DELETE /admin/v1/admins/[administrator_id]
Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | The administrator was deleted or did not exist. |
Response Format
Empty string.
Example Response
{
"stat": "OK",
"response": ""
}
Clear the number of failed login attempts for the administrator with administrator_id
. Re-enables an administrator who has been disabled due to too many failed authentication attempts.
POST /admin/v1/admins/[administrator_id]/reset
Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | The administrator’s authentication failure count was set to zero. |
404 |
No administrator was found with the given administrator_id .
|
Response Format
Empty string.
Example Response
{
"stat": "OK",
"response": ""
}
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).
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. |
send_email
|
Optional | If set to “1”, the activation link and an introductory message will be emailed to the new administrator. If set to “0”, no email is sent, and the link is returned to the API method’s caller only. Default: “0”. |
valid_days
|
Optional | Number of days before the link expires. Default: 7. Maximum days: 31. |
admin_role
|
Optional |
The administrator’s role. One of: “Owner”, “Administrator”, “Application Manager”, “User Manager”, “Help Desk”, “Billing”, “Phishing Manager”, or “Read-only”. The role names are case-sensitive. Defaults to “Owner” if not specified. Roles other than “Owner” are effective only if the customer edition includes the Administrative Roles feature. |
Response Codes
Response | Meaning |
---|---|
200 | Activation link is returned (and optionally emailed). |
400 |
Invalid or missing parameters, or email is already in use by an existing administrator or pending activation request.
|
Response Format
Key | Value |
---|---|
admin_activation_id
|
The ID of the administrator activation link. |
admin_role
|
The administrator role assigned to the new admin. |
code
|
Activation code used to create this activation link and message. |
email
|
Email address supplied by the caller. If the activation form is completed a new administrator will be created with this email address. |
email_sent
|
“1” if the introductory message was emailed to the new administrator; “0” otherwise. |
expires
|
Timestamp of the activation link's expiration. |
link
|
Link to the activation form. |
message
|
Introductory message body. |
subject
|
Introductory message subject. |
valid_days
|
Number of days before the activation link expires. |
Example Response
{
"response": {
"admin_activation_id": "DK9PHLB5Z8NZJRFSJX4Q",
"admin_role": "Read-only",
"code": "g793cfba2b4e8684164c6b8766baad08",
"email": "sogilby@example.com",
"email_sent": 1,
"expires": 1550075404,
"link": "https://admin-abcd1234.duosecurity.com/activation/g793cfba2b4e8684164c6b8766baad08",
"message": "\nWelcome to Duo!\n\nThis email contains an activation link that will allow you to create an account to access the Duo administrative web interface for Acme Corp.\n\nPlease click on the following link to create the account and fill in the required information:\n\nhttps://admin-abcd1234.duosecurity.com/activation/g793cfba2b4e8684164c6b8766baad08\n\nThanks for using the Duo platform for your authentication needs!\n",
"subject": "Welcome to Duo!",
"valid_days": 7
},
"stat": "OK"
}
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.
GET /admin/v1/admins/activations
Parameters
Paging Parameter | Required? | Description |
---|---|---|
limit
|
Optional |
The maximum number of records returned. Default: 100; Max: 500 |
offset
|
Optional |
The offset from 0 at which to start record retrieval. When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: 0 |
Response Codes
Response | Meaning |
---|---|
200 | A list of pending admin activations is returned. |
400 | Invalid paging parameters. |
Response Format
Key | Value |
---|---|
admin_activation_id
|
The ID of the administrator activation link. |
code
|
Activation code used to create this activation link and message. |
email
|
Email address supplied by the caller. If the activation form is completed a new administrator will be created with this email address. |
expires
|
Timestamp of the activation link's expiration. |
Example Response
{
"response": {
"admin_activation_id": "DK9PHLB5Z8NZJRFSJX4Q",
"code": "g793cfba2b4e8684164c6b8766baad08",
"email": "sogilby@example.com",
"expires": 1550075404
},
"stat": "OK"
}
Delete the pending admin activation with ID admin_activation_id
from the system.
DELETE /admin/v1/admins/activations/[admin_activation_id]
Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | The pending admin activation link was deleted or did not exist. |
404 |
Invalid admin_activation_id format.
|
Response Format
Empty string.
Example Response
{
"stat": "OK",
"response": ""
}
This legacy activation endpoint will be limited or deprecated in the future. Consider using the new /admin/v1/admins/activations
endpoint, which includes GET
and DELETE
methods for viewing and deleting pending admin enrollments.
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).
POST /admin/v1/admins/activate
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. |
send_email
|
Optional | If set to “1”, the activation link and an introductory message will be emailed to the new administrator. If set to “0”, no email is sent, and the link is returned to the API method’s caller only. Default: “0”. |
valid_days
|
Optional | Number of days before the link expires. Default: 7. Maximum days: 31. |
admin_role
|
Optional |
The administrator’s role. One of: “Owner”, “Administrator”, “Application Manager”, “User Manager”, “Help Desk”, “Billing”, “Phishing Manager”, or “Read-only”. The role names are case-sensitive. Defaults to “Owner” if not specified. Roles other than “Owner” are effective only if the customer edition includes the Administrative Roles feature. |
Response Codes
Response | Meaning |
---|---|
200 | Activation link is returned (and optionally emailed). |
400 |
Invalid or missing parameters, or email is already in use by an existing administrator or pending activation request.
|
Response Format
Key | Value |
---|---|
admin_activation_id
|
The ID of the administrator activation link. |
admin_role
|
The administrator role assigned to the new admin. |
code
|
Activation code used to create this activation link and message. |
email
|
Email address supplied by the caller. If the activation form is completed a new administrator will be created with this email address. |
email_sent
|
“1” if the introductory message was emailed to the new administrator; “0” otherwise. |
expires
|
Timestamp of the activation link's expiration. |
link
|
Link to the activation form. |
message
|
Introductory message body. |
subject
|
Introductory message subject. |
valid_days
|
Number of days before the activation link expires. |
Example Response
{
"response": {
"admin_activation_id": "DK9PHLB5Z8NZJRFSJX4Q",
"admin_role": "Read-only",
"code": "g793cfba2b4e8684164c6b8766baad08",
"email": "sogilby@example.com",
"email_sent": 0,
"link": "https://admin-abcd1234.duosecurity.com/activation/g793cfba2b4e8684164c6b8766baad08",
"message": "\nWelcome to Duo!\n\nThis email contains an activation link that will allow you to create an account to access the Duo administrative web interface for Acme Corp.\n\nPlease click on the following link to create the account and fill in the required information:\n\nhttps://admin-abcd1234.duosecurity.com/activation/g793cfba2b4e8684164c6b8766baad08\n\nThanks for using the Duo platform for your authentication needs!\n",
"subject": "Welcome to Duo!",
"valid_days": 7
},
"stat": "OK"
}
Retrieve a list of the secondary authentication methods permitted for administrator log on to the Duo Admin Panel.
GET /admin/v1/admins/allowed_auth_methods
Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
Response Format
Key | Value |
---|---|
hardware_token_enabled
|
If true, administrators may authenticate to the Duo Admin Panel with an OTP hardware token. If false, administrators may not use OTP hardware tokens. |
mobile_otp_enabled
|
If true, administrators may authenticate to the Duo Admin Panel with a passcode generated by the Duo Mobile app. If false, administrators may not use Duo Mobile passcodes. |
push_enabled
|
If true, administrators may authenticate to the Duo Admin Panel by approving a push request in the Duo Mobile app. If false, administrators may not approve login with Duo Push. |
sms_enabled
|
If true, administrators may authenticate to the Duo Admin Panel with a passcode received via SMS. If false, administrators may not use SMS passcodes. |
voice_enabled
|
If true, administrators may authenticate to the Duo Admin Panel by approving the request received via phone call. If false, administrators may not approve login with a phone call. |
yubikey_enabled
|
If true, administrators may authenticate to the Duo Admin Panel with a Yubikey token. If false, administrators may not use Yubikey tokens. |
Example Response
{
"stat": "OK",
"response": {
"hardware_token_enabled": true,
"mobile_otp_enabled": true,
"push_enabled": true,
"sms_enabled": false,
"voice_enabled": false,
"yubikey_enabled": true
}
}
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.
POST /admin/v1/admins/allowed_auth_methods
Parameters
Parameter | Required? | Description |
---|---|---|
hardware_token_enabled
|
Optional, but at least one valid factor must be set to true. | If true, administrators may authenticate to the Duo Admin Panel with an OTP hardware token. If false or not specified, administrators may not use OTP hardware tokens. |
mobile_otp_enabled
|
Optional, but at least one valid factor must be set to true. | If true, administrators may authenticate to the Duo Admin Panel with a passcode generated by the Duo Mobile app. If false or not specified, administrators may not use Duo Mobile passcodes. |
push_enabled
|
Optional, but at least one valid factor must be set to true. | If true, administrators may authenticate to the Duo Admin Panel by approving a push request in the Duo Mobile app. If false or not specified, administrators may not approve login with Duo Push. |
sms_enabled
|
Optional, but at least one valid factor must set to true. | If true, administrators may authenticate to the Duo Admin Panel with a passcode received via SMS. If false or not specified, administrators may not use SMS passcodes. |
voice_enabled
|
Optional, but at least one valid factor must be set to true. | If true, administrators may authenticate to the Duo Admin Panel by approving the request received via phone call. If false or not specified, administrators may not approve login with a phone call. |
yubikey_enabled
|
Optional, but at least one valid factor must be set to true. | If true, administrators may authenticate to the Duo Admin Panel with a Yubikey token. If false or not specified, administrators may not use Yubikey tokens. |
Response Codes
Response | Meaning |
---|---|
200 | The settings were modified successfully. The settings object is also returned (see Retrieve Administrator Authentication Factors). |
400 | Invalid or missing parameters. For example, no valid factor was specified. |
Response Format
Same as Retrieve Administrator Authentication Factors
Example Response
Same as Retrieve Administrator Authentication Factors
Returns a paged list of ist 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.
Optionally specify at most one parameter to return a list of administrative units associated with the given administrator, group, or integration.
GET /admin/v1/administrative_units
Parameters
Paging Parameter | Required? | Description |
---|---|---|
limit
|
Optional |
The maximum number of records returned. Default: 100; Max: 500 |
offset
|
Optional |
The offset from 0 at which to start record retrieval. When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: 0 |
Query Parameter | Required? | Description |
---|---|---|
admin_id
|
Optional |
A Duo administrator's admin_id .
|
group_id
|
Optional |
A Duo group's group_id .
|
integration_key
|
Optional |
The integration_key for a Duo integration.
|
Response Codes
Response | Meaning |
---|---|
200 | Success. |
404 |
No administrative unit was found with the given admin_id , group_id , or integration_key .
|
Response Format
Key | Value |
---|---|
admin_unit_id
|
The administrative unit's unique ID. |
name
|
The administrative unit's name. |
description
|
The administrative unit's description. |
restrict_by_groups
|
Does the administrative unit specify groups? Either “true” or “false”. |
restrict_by_integrations
|
Does the administrative unit specify integrations? Either “true” or “false”. |
Example Response
{
"stat": "OK",
"response": [{
"admin_unit_id": "AUT0HJ753KH67HGF4S7H",
"description": "Acme Corp Europe, Middle East, and Africa",
"name": "Acme EMEA",
"restrict_by_groups": true,
"restrict_by_integrations": true
},
{
"admin_unit_id": "AUDJ753KH6Z252X1B2B4",
"description": "Acme Corp United States",
"name": "Acme USA",
"restrict_by_groups": true,
"restrict_by_integrations": true
}]
}
Returns details for a single administrative unit with admin_unit_id
.
GET /admin/v1/administrative_units/[admin_unit_id]
Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
404 |
No administrative unit was found with the given admin_unit_id .
|
Response Format
Key | Value |
---|---|
admin_unit_id
|
The administrative unit's unique ID. |
name
|
The administrative unit's name. |
description
|
The administrative unit's description. |
restrict_by_groups
|
Does the administrative unit specify groups? Either “true” or “false”. |
restrict_by_integrations
|
Does the administrative unit specify integrations? Either “true” or “false”. |
admins
|
The administrators assigned to the new administrative unit, listed by admin_id .
|
groups
|
The groups assigned to the new administrative unit, listed by group_id .
|
integrations
|
The integrations assigned to the new administrative unit, listed by integration_key .
|
Example Response
{
"stat": "OK",
"response": [{
"admin_unit_id": "AUTU3AA76HG76K9GPFJ2",
"admins": [
"DEA76HG76K45TQHBMFI4"
],
"description": "Acme Networking and VPN Admins",
"groups": [],
"integrations": [
"DIBA76HEQMHRWA76KSSH"
],
"name": "Acme Net Admins",
"restrict_by_groups": false,
"restrict_by_integrations": true
}
}
Add a new administrative unit with specified administrators, groups, or other parameters.
POST /admin/v1/administrative_units
Parameters
Parameter | Required? | Description |
---|---|---|
name
|
Required |
The name of the new administrative unit. Must be unique amongst all administrative units. |
description
|
Required |
A description of the new administrative unit. |
restrict_by_groups
|
Required |
Does the new administrative unit specify groups? Default: “false”. |
restrict_by_integrations
|
Optional |
Does the new administrative unit specify integrations? Default: “false”. |
admins
|
Optional |
One or more |
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.
Change the name, description, assigned administrators, groups, and/or integrations of the administrative unit with admin_unit_id
.
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.
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.
POST /admin/v1/administrative_units/[admin_unit_id]/admin/[admin_id]
Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | The administrative unit was modified. Also returns unit details. |
400 |
Invalid admin_unit_id or admin_id , or the restricted_by_admin_units value is "false" for that administrator.
|
Response Format
Same as Retrieve Administrative Unit Details.
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.
DELETE /admin/v1/administrative_units/[admin_unit_id]/admin/[admin_id]
Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | The administrative unit was modified. Also returns unit details. |
400 |
Invalid admin_unit_id or admin_id .
|
Response Format
Same as Retrieve Administrative Unit Details.
Assign the group with group_id
to the administrative unit with admin_unit_id
.
POST /admin/v1/administrative_units/[admin_unit_id]/group/[group_id]
Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | The administrative unit was modified. Also returns unit details. |
400 |
Invalid admin_unit_id or group_id .
|
Response Format
Same as Retrieve Administrative Unit Details.
Unassign the group with group_id
from the administrative unit with admin_unit_id
.
DELETE /admin/v1/administrative_units/[admin_unit_id]/group/[group_id]
Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | The administrative unit was modified. Also returns unit details. |
400 |
Invalid admin_unit_id or group_id .
|
Response Format
Same as Retrieve Administrative Unit Details.
Assign the integration with integration_key
to the administrative unit with admin_unit_id
.
POST /admin/v1/administrative_units/[admin_unit_id]/integration/[integration_key]
Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | The administrative unit was modified. Also returns unit details. |
400 |
Invalid admin_unit_id or integration_key .
|
Response Format
Same as Retrieve Administrative Unit Details.
Unassign the integration with admin_id
from the administrative unit with admin_unit_id
.
DELETE /admin/v1/administrative_units/[admin_unit_id]/integration/[integration_key]
Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | The administrative unit was modified. Also returns unit details. |
400 |
Invalid admin_unit_id or integration_key .
|
Response Format
Same as Retrieve Administrative Unit Details.
Delete the administrative unit with admin_unit_id
from the system.
DELETE /admin/v1/administrative_units/[admin_unit_id]
Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | The administrative unit was deleted or did not exist. |
Response Format
Empty string.
Example Response
{
"stat": "OK",
"response": ""
}
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 offset parameter as long as the result metadata has next_offset
values.
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.
The v2 handler provides new filtering and querying capabilities unavailable in the legacy v1 handler. This includes the ability to filter on users, groups, applications, authentication results, factors, and time ranges.
GET or POST /admin/v2/logs/authentication
Parameters
Paging Parameter | Required? | Allow Multiple? | Description | ||||||
---|---|---|---|---|---|---|---|---|---|
limit
|
Optional | No |
The maximum number of records returned. Default: 100; Max: 1000 |
||||||
next_offset
|
Optional | Yes |
The offset at which to start record retrieval. This value is provided in the metadata in the form of a 13 character date string in milliseconds and the event When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: None |
||||||
sort
|
Optional | No |
The order in which to return records. One of:
|
Query Parameter | Required? | Allow Multiple? | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
mintime
|
Required | No |
Return records that have a 13 character Unix |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
maxtime
|
Required | No |
Return records that have a 13 character Unix |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
users
|
Optional |
Yes. Multiple values create an OR query.
|
A user's Default: Return logs for all users. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
groups
|
Optional |
Yes. Multiple values create an OR query.
|
A group's Default: Return logs for all groups. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
applications
|
Optional |
Yes. Multiple values create an OR query.
|
An integrations's Default: Return logs for all applications. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
factors
|
Optional |
Yes. Multiple values create an OR query.
|
The factor or method used for an authentication attempt. One of:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
event_types
|
Optional |
Yes. Multiple values create an OR query.
|
The type of authentication event. One of:
|
Response Codes
Response | Meaning |
---|---|
200 | Success. |
400 |
Invalid or missing parameters or mintime is after the maxtime .
|
Response Format
Key | Value | ||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
access_device
|
Browser, plugin, and operating system information for the endpoint used to access the Duo-protected resource. Values present only when the application accessed features Duo’s inline browser prompt. This information is available to Duo Beyond and Duo Access plan customers.
|
||||||||||||||||||||||||
application
|
Information about the application accessed.
|
||||||||||||||||||||||||
auth_device
|
Information about the device used to approve or deny authentication.
|
||||||||||||||||||||||||
event_type
|
The type of activity logged. one of: “authentication” or “enrollment”. | ||||||||||||||||||||||||
factor
|
The authentication factor. One of: “phone_call”, “passcode”, “yubikey_passcode”, “digipass_go_7_token”, “hardware_token”, “duo_mobile_passcode”, “bypass_code”, “sms_passcode”, “sms_refresh”, “duo_push”, “u2f_token”, “remembered_device”, or “trusted_network'”. |
||||||||||||||||||||||||
reason
|
Provide the reason for the authentication attempt result. If result is “SUCCESS” then one of: “allow_unenrolled_user”, “allowed_by_policy”, “allow_unenrolled_user_on_trusted_network”, “bypass_user”, “remembered_device”, “trusted_location”, “trusted_network”, “user_approved”, “valid_passcode”. If result is “FAILURE” then one of: “anonymous_ip”, “anomalous_push”, “could_not_determine_if_endpoint_was_trusted”, “denied_by_policy”, “denied_network”, “deny_unenrolled_user”, “endpoint_is_not_in_management_system”, “endpoint_failed_google_verification”, “endpoint_is_not_trusted”, “factor_restricted”, “invalid_management_certificate_collection_state”, “invalid_device”, “invalid_passcode”, “invalid_referring_hostname_provided”, “location_restricted”, “locked_out”, “no_activated_duo_mobile_account”, “no_disk_encryption”, “no_duo_certificate_present”, “touchid_disabled”, “no_referring_hostname_provided”, “no_response”, “no_screen_lock”, “no_web_referer_match”, “out_of_date”, “platform_restricted”, “rooted_device”, “software_restricted”, “user_cancelled”, “user_disabled”, “user_mistake”, “user_not_in_permitted_group”, “user_provided_invalid_certificate”, or “version_restricted”. If result is “ERROR” then: “error”. If result is “FRAUD” then: “user_marked_fraud”. |
||||||||||||||||||||||||
result
|
The result of the authentication attempt. One of: “SUCCESS”, “FAILURE”, “ERROR”, or “FRAUD”. | ||||||||||||||||||||||||
timestamp
|
Unix timestamp of the event. | ||||||||||||||||||||||||
txid
|
The transaction ID of the event. | ||||||||||||||||||||||||
user
|
Information about the authenticating user.
|
Example Response
200 OK
{
"response": {
"authlogs": [
{
"access_device": {
"browser": "Chrome",
"browser_version": "67.0.3396.99",
"flash_version": "uninstalled",
"hostname": "null",
"ip": "169.232.89.219",
"java_version": "uninstalled",
"location": {
"city": "Ann Arbor",
"country": "United States",
"state": "Michigan"
},
"os": "Mac OS X",
"os_version": "10.14.1"
},
"application": {
"key": "DIY231J8BR23QK4UKBY8",
"name": "Microsoft Azure Active Directory"
},
"auth_device": {
"ip": "192.168.225.254",
"location": {
"city": "Ann Arbor",
"country": "United States",
"state": "Michigan"
},
"name": "My iPhone X (734-555-2342)"
},
"event_type": "authentication",
"factor": "duo_push",
"reason": "user_approved",
"result": "success",
"timestamp": 1532951962,
"trusted_endpoint_status": "not trusted",
"txid": "340a23e3-23f3-23c1-87dc-1491a23dfdbb",
"user": {
"key": "DU3KC77WJ06Y5HIV7XKQ",
"name": "narroway@example.com"
}
},
],
"metadata": {
"next_offset": [
"1532951895000",
"af0ba235-0b33-23c8-bc23-a31aa0231de8"
],
"total_objects": 1
}
},
"stat": "OK"
}
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.
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
.
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 Beyond and Duo Access plan customers.
|
||||||||||||||
device
|
Device used to authenticate, if present, otherwise none. | ||||||||||||||
factor
|
The authentication factor. One of: “Bypass Code”, “Digipass GO 7 Token”, “Duo Mobile Passcode”, “Duo Push”, “Passcode”, “Phone Call”, “Hardware Token”, “Remembered Device”, “Security Key (WebAuthn)”, “SMS Passcode”, “SMS Refresh”, “Touch ID (WebAuthn)”, “Trusted Network”, “U2F Token”, or “Yubikey Passcode”. |
||||||||||||||
integration
|
The integration name. | ||||||||||||||
ip
|
The IP address that this request originated from. | ||||||||||||||
location
|
The GeoIP location from which the user authenticated, if available. The response may not include all location parameters. | ||||||||||||||
city
|
The city name. | ||||||||||||||
state
|
The state, county, province, or prefecture. | ||||||||||||||
country
|
The country code. | ||||||||||||||
new_enrollment
|
“True” if the user enrolled a new device at the authentication prompt; “False” if authenticated with a previously enrolled device. | ||||||||||||||
reason
|
Provide the reason for the authentication attempt result. If result is “SUCCESS” then one of: “Allow unenrolled user”, “Allowed by policy”, “Bypass user”, “Remembered device”, “Trusted location”, “Trusted network”, “User approved”, “Valid passcode”. If result is “FAILURE” then one of: “Anonymous IP”, “Anomalous push”, “Call timed out”, “Couldn't determine if endpoint was trusted”, “Denied by policy”, “Deny unenrolled user”, “Endpoint is not in Management System”, “Factor restricted”, “Invalid device”, “Invalid passcode”, “Location restricted”, “Locked out”, “No Duo certificate present”, “No response”, “No disk encryption”, “No fingerprint”, “No screen lock”, “Out of date”, “Platform restricted”, “Rooted device”, “Software Restricted”, “User cancelled”, “User is disabled”, “User mistake”, “User provided an invalid certificate”, or “Version restricted”. If result is “ERROR” then: “Error”. If result is “FRAUD” then: “User marked fraud”. |
||||||||||||||
result
|
The result of the authentication attempt. One of: “SUCCESS”, “FAILURE”, “ERROR”, or “FRAUD”. | ||||||||||||||
timestamp
|
Unix timestamp of the event. | ||||||||||||||
username
|
The authenticating user’s username. |
Example Response
{
"stat": "OK",
"response": [{
"access_device": {
"browser": "Chrome",
"browser_version": "56.0.2924.87",
"flash_version": "25.0.0.0",
"java_version": "1.8.0.92",
"os": "Mac OS X",
"os_version": "10.11"
"trusted_endpoint_status": "trusted"
},
"device": "503-555-1000",
"factor": "Duo Push",
"integration": "Acme Intranet",
"ip": "192.168.0.1",
"location": {
'city': 'Ann Arbor',
'state': 'Michigan',
'country': 'US'
},
"new_enrollment": false,
"reason": "User Approved",
"result": "SUCCESS",
"timestamp": 1346172697,
"username": "jsmith",
}]
}
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.
GET /admin/v1/logs/administrator
Parameters
Parameter | Required? | Description |
---|---|---|
mintime
|
Optional |
Only return records that have a Unix timestamp after mintime . This can help to avoid fetching records that have already been retrieved.
|
Response Codes
Response | Meaning |
---|---|
200 | Success. |
Response Format
Key | Value | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
timestamp
|
Unix timestamp of the event. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
username
|
The full name of the administrator who performed the action in the Duo Admin Panel. If the action was performed with the API this will be “API”. Automatic actions like deletion of inactive users have “System” for the username. Changes synchronized from Active Directory will have a username of the form “AD Sync: name of directory.” | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
action
|
The type of change that was performed. Possible values:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
description
|
String detailing what changed, either as free-form text or serialized JSON. When the description contains JSON it may be either a serialized object or a serialized array of objects. Each key in the object(s) corresponds to a property that was changed. This JSON is intended only to summarize the change, not to be de-serialized.
The first example below is for a “user_update” action. The object that changed was a user whose Duo username is “jsmith”. The change saved new values for the user’s “notes” and “realname” fields, overwriting the previous values if any were set. They correspond to the similarly named fields in the Modify User call in the Admin API and the User Details page in the Admin Panel. The second example shows an “admin_login_error” action. The administrator's login attempt failed because the admin attempted to use SSO but, as indicated by the “error” in the description, SAML login is disabled for administrators on that account. |
Example Responses
{
"stat": "OK",
"response": [{
"action": "user_update",
"description": "{\"notes\": \"Joe asked for their nickname to be displayed instead of Joseph.\", \"realname\": \"Joe Smith\"}",
"object": "jsmith",
"timestamp": 1346172820,
"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\"}",
"object": null,
"timestamp": 1446172820,
"username": ""
}]
}
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.
GET /admin/v1/logs/telephony
Parameters
Parameter | Required? | Description |
---|---|---|
mintime
|
Optional |
Only return records that have a Unix timestamp after mintime . This can help to avoid fetching records that have already been retrieved.
|
Response Codes
Response | Meaning |
---|---|
200 | Success. |
Response Format
Key | Value |
---|---|
timestamp
|
Unix timestamp of the event. |
context
|
How this telephony event was initiated. One of: “administrator login”, “authentication”, “enrollment”, or “verify”. |
type
|
The event type. Either “sms” or “phone”. |
phone
|
The phone number that initiated this event. |
credits
|
How many telephony credits this event cost. |
Example Response
{
"stat": "OK",
"response": [{
"context": "authentication",
"credits": 1,
"phone": "+15035550100",
"timestamp": 1346172697,
"type": "sms"
}]
}
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.
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
.
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.
|
||||||
object
|
The Duo Windows Logon integration's name .
|
||||||
timestamp
|
Unix timestamp of the event. | ||||||
username
|
The Duo username. |
Example Response
{
"stat": "OK",
"response": [{
"action": "o2fa_user_provisioned",
"description": "{\"user_agent\": \"DuoCredProv/4.0.6.413 (Windows NT 6.3.9600; x64; Server)\", \"hostname\": \"WKSW10x64\", \"factor\": \"duo_otp\"}",
"object": "Acme Laptop Windows Logon",
"timestamp": 1542651392,
"username": "narroway"
}]
}
Returns settings. These settings can also be viewed and set in the Admin Interface.
GET /admin/v1/settings
Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | Success. Returns settings. |
Response Format
Key | Value |
---|---|
caller_id
|
Automated calls will appear to come from this number. This does not apply to text messages. |
fraud_email
|
The email address to be notified when a user reports a fraudulent authentication attempt or is locked out due to failed authentication attempts. All administrators will be notified if this is not set. |
fraud_email_enabled
|
If true, emailed notifications of user-reported fraudulent authentication attempts and user lockouts due to failed authentication are sent to the email address defined for fraud_email, or to all administrators if fraud_email is not defined. If set to false, no fraud alert emails are sent. |
inactive_user_expiration
|
Users will be automatically deleted if they are inactive (no successful logins) for a this amount of days. |
keypress_confirm
|
The key for users to press to authenticate, or empty if any key should be pressed to authenticate. |
keypress_fraud
|
The key for users to press to report fraud, or empty if any key should be pressed to authenticate. |
language
|
The language used in the browser-based user authentication prompt. One of: “EN”, “DE”, “FR”. Default: “EN” |
lockout_expire_duration
|
If non-zero, the time in minutes until a locked-out user’s status reverts to “Active”. If “null” or “0”, a user remains locked out until their status is manually changed (By an admin or API call). Minimum: 5 minutes. Maximum: 30000 minutes. |
lockout_threshold
|
The number of consecutive failed authentication attempts before the user’s status is set to “Locked Out” and the user is denied access. |
minimum_password_length
|
The minimum number of characters that an administrator’s Duo Admin Panel password must contain. This is only enforced on password creation and reset; existing passwords will not be invalidated. Default: 12. |
mobile_otp_enabled
|
If true, users will be able to use authenticate with a passcode generated by Duo Mobile. If false, users will not be able to authenticate with a passcode generated by Duo Mobile. Note that if false, this will override Duo Mobile passcodes for any groups. |
name
|
The customer name. |
password_requires_lower_alpha
|
If true, administrator passwords will be required to contain a lower case alphabetic character. If false, administrator passwords will not be required to contain a lower case alphabetic character. This is only enforced on password creation and reset; existing passwords will not be invalidated. Default: false. |
password_requires_numeric
|
If true, administrator passwords will be required to contain a numeric character. If false, administrator passwords will not be required to contain a numeric character. This is only enforced on password creation and reset; existing passwords will not be invalidated. Default: false. |
password_requires_special
|
If true, administrator passwords will be required to contain a special (non-alphanumeric) character. If false, administrator passwords will not be required to contain a special (non-alphanumeric) character. This is only enforced on password creation and reset; existing passwords will not be invalidated. Default: false. |
password_requires_upper_alpha
|
If true, administrator passwords will be required to contain an upper case alphabetic character. If false, administrator passwords will not be required to contain an upper case alphabetic character. This is only enforced on password creation and reset; existing passwords will not be invalidated. Default: false. |
push_enabled
|
If true, users will be able to use Duo Push to authenticate. If false, users will not be able to use Duo Push to authenticate. Note that if false, this will override push_enabled for any groups. |
sms_batch
|
How many passcodes to send at one time, up to 10. |
sms_enabled
|
If true, users will be able to use SMS passcodes to authenticate. If false, users will not be able to use SMS passcodes to authenticate. Note that if false, this will override sms_enabled for any groups. |
sms_expiration
|
The time in minutes to expire and invalidate SMS passcodes. |
sms_message
|
Description sent with every batch of SMS passcodes. |
sms_refresh
|
If “1”, a new set of SMS passcodes will automatically be sent after the last one is used. If “0”, a new set will not be sent. |
telephony_warning_min
|
This is the number of telephony credits at which an alert will be sent for low credits. |
timezone
|
This is the timezone used when displaying timestamps in the administrative interface. |
voice_enabled
|
If true, users will be able to use authenticate with voice callback. If false, users will not be able to authenticate with voice callback. Note that if false, this will override voice_enabled for any groups. |
user_telephony_cost_max
|
The maximum number of telephony credits a user may consume in a single authentication event. This excludes Duo administrators authenticating to the Duo administration panel. Default: 20. |
u2f_enabled
|
If true, users will be able to use authenticate with a U2F device. If false, users will not be able to authenticate with a U2F device. Default: false. |
Example Response
{
"stat": "OK",
"response": {
"caller_id": "+15035551000",
"fraud_email": "example@example.com",
"fraud_email_enabled": true,
"helpdesk_bypass": "allow",
"helpdesk_bypass_expiration": 0,
"inactive_user_expiration": 30,
"keypress_confirm": "#",
"keypress_fraud": "*",
"language": "EN",
"lockout_expire_duration": null,
"lockout_threshold": 10,
"log_retention_days": null,
"minimum_password_length": 12,
"mobile_otp_enabled": true,
"name": "Acme Corp",
"password_requires_lower_alpha": true,
"password_requires_numeric": true,
"password_requires_special": false,
"password_requires_upper_alpha": true,
"push_enabled": true,
"req_fips_passcodes_android": false,
"security_checkup_enabled": 1,
"sms_batch": 1,
"sms_enabled": true,
"sms_expiration": 10,
"sms_message": "SMS passcodes",
"sms_refresh": 0,
"telephony_warning_min": 0,
"timezone": "UTC",
"user_telephony_cost_max": 20.0,
"voice_enabled": true,
}
}
Change settings.
POST /admin/v1/settings
Parameters
Parameter | Required? | Description |
---|---|---|
caller_id
|
Optional | Automated calls will appear to come from this number. This does not apply to text messages. |
fraud_email
|
Optional | The email address to be notified when a user reports a fraudulent authentication attempt or is locked out due to failed authentication attempts, or empty for all administrators will be notified. If fraud_email is set to a specific email address and fraud_email_enabled is set to false, the specific email address value is cleared. |
fraud_email_enabled
|
Optional | Set to true to enable fraudulent authentication notification emails. False disables the fraud email functionality. If fraud_email is set to a specific email address and fraud_email_enabled is set to false, the specific email address value is cleared. |
inactive_user_expiration
|
Optional | Users will be automatically deleted if they are inactive (no successful logins) for a this amount of days. Minimum: 30 days. Maximum: 365 days. |
keypress_confirm
|
Optional |
The key for users to press to authenticate, or empty if any key should be pressed to authenticate. If this is empty, keypress_fraud must be as well.
|
keypress_fraud
|
Optional |
The key for users to report fraud, or empty if any key should be pressed to authenticate. If this is empty, keypress_confirm must be as well.
|
language
|
Optional | Sets the language used in the browser-based user authentication prompt. One of: “EN”, “DE”, “FR”. Default: “EN” |
lockout_expire_duration
|
Optional | If non-zero, the time in minutes until a locked-out user’s status reverts to “Active”. If 0, a user remains locked out until their status is manually changed (By an admin or API call). Minimum: 5 minutes. Maximum: 30000 minutes. |
lockout_threshold
|
Optional | The number of consecutive failed authentication attempts before the user’s status is set to “Locked Out” and the user is denied access. |
minimum_password_length
|
Optional | The minimum number of characters that an administrator’s Duo Admin Panel password must contain. This is only enforced on password creation and reset; existing passwords will not be invalidated. Default: 12. |
mobile_otp_enabled
|
Optional | If true, users will be able to use authenticate with a passcode generated by Duo Mobile. If false, users will not be able to authenticate with a passcode generated by Duo Mobile. Note that if false, this will override Duo Mobile passcodes for any groups. |
password_requires_lower_alpha
|
Optional | If true, administrator passwords will be required to contain a lower case alphabetic character. If false, administrator passwords will not be required to contain a lower case alphabetic character. This is only enforced on password creation and reset; existing passwords will not be invalidated. Default: false. |
password_requires_numeric
|
Optional | If true, administrator passwords will be required to contain a numeric character. If false, administrator passwords will not be required to contain a numeric character. This is only enforced on password creation and reset; existing passwords will not be invalidated. Default: false. |
password_requires_special
|
Optional | If true, administrator passwords will be required to contain a special (non-alphanumeric) character. If false, administrator passwords will not be required to contain a special (non-alphanumeric) character. This is only enforced on password creation and reset; existing passwords will not be invalidated. Default: false. |
password_requires_upper_alpha
|
Optional | If true, administrator passwords will be required to contain an upper case alphabetic character. If false, administrator passwords will not be required to contain an upper case alphabetic character. This is only enforced on password creation and reset; existing passwords will not be invalidated. Default: false. |
push_enabled
|
Optional | If true, users will be able to use Duo Push to authenticate. If false, users will not be able to use Duo Push to authenticate. Note that if false, this will override push_enabled for any groups. |
sms_batch
|
Optional | How many passcodes to send at one time, up to 10. |
sms_enabled
|
Optional | If true, users will be able to use SMS passcodes to authenticate. If false, users will not be able to use SMS passcodes to authenticate. Note that if false, this will override sms_enabled for any groups. |
sms_expiration
|
Optional | The time in minutes to expire and invalidate SMS passcodes, or empty if they should not expire. |
sms_message
|
Optional | Description sent with every batch of SMS passcodes. |
sms_refresh
|
Optional | If 1, a new set of SMS passcodes will automatically be sent after the last one is used. If 0, a new set will not be sent. |
telephony_warning_min
|
Optional | Configure a alert to be sent when the account has fewer than this many telephony credits remaining. |
timezone
|
Optional | This is the timezone used when displaying timestamps in the administrative interface. Timezones must be entries in the IANA Time Zone Database, for example, “US/Eastern”, “Australia/Darwin”, “GMT”. |
voice_enabled
|
Optional | If true, users will be able to authenticate using voice callback. If false, users will not be able to authenticate using voice callback. Note that if false, this will override voice_enabled for any groups. |
user_telephony_cost_max
|
Optional | The maximum number of telephony credits a user may consume in a single authentication event. This excludes Duo administrators authenticating to the Duo administration panel. Default: 20. |
u2f_enabled
|
Optional | If true, users will be able to use authenticate with a U2F device. If false, users will not be able to authenticate with a U2F device. Default: false. |
Response Codes
Response | Meaning |
---|---|
200 | The settings were modified successfully. The settings object is also returned (see Retrieve Settings). |
400 |
Invalid or missing parameters.
For example, inactive_user_expiration out of bounds.
|
Response Format
Same as Retrieve Settings.
Example Response
Same as Retrieve Settings.
Returns the logo to display in Duo Mobile.
GET /admin/v1/logo
Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | Success. Returns PNG data. |
404 | No logo currently configured. |
Response Format
If there are no errors, a PNG image is returned instead of JSON and the Content-Type header is image/png.
Set or replace the logo to display in Duo Mobile. This logo is sent to devices when they enroll with the mobile app. Currently enrolled devices must be re-activated to receive the new logo.
POST /admin/v1/logo
Parameters
Parameter | Required? | Description |
---|---|---|
logo
|
Required | Base-64 encoded PNG image data. |
Response Codes
Response | Meaning |
---|---|
200 | Success. |
400 | Invalid or missing parameters or PNG data. |
Response Format
Empty string.
Remove the logo from future activation of Duo Mobile. Currently enrolled devices must be re-activated to remove the logo.
DELETE /admin/v1/logo
Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | The logo was deleted or did not exist. |
Response Format
Empty string.
Returns a summary of account usage information.
GET /admin/v1/info/summary
Parameters
None.
Response Codes
Response | Meaning |
---|---|
200 | Success. |
Response Format
Key | Value |
---|---|
admin_count
|
Current number of admins in the account. |
integration_count
|
Current number of integrations in the account. |
telephony_credits_remaining
|
Current total number of telephony credits available in the account. This is the sum of all types of telephony credits. |
user_count
|
Current number of users in the account. |
Example Response
{
"stat": "OK",
"response": {
"admin_count": 3,
"integration_count": 9,
"telephony_credits_remaining": 960,
"user_count": 8
}
}
Retrieve the number of telephony credits used in a given time period.
If the specified time period is too long you may need to call this multiple times with mintime
and sum the results.
GET /admin/v1/info/telephony_credits_used
Parameters
Parameter | Required? | Description |
---|---|---|
maxtime | Optional | Limit report to events before this UNIX timestamp. Defaults to the current time. |
mintime | Optional |
Limit report to events after this UNIX timestamp. Defaults to thirty days before maxtime .
|
Response Codes
Response | Meaning |
---|---|
200 | Success. |
400 |
Invalid or missing parameters or mintime is after the maxtime .
|
Response Format
Key | Value |
---|---|
mintime
|
UNIX timestamp for the beginning of the report period. |
maxtime
|
UNIX timestamp for the end of the report period. |
telephony_credits_used
|
Number of telephony credits spent during the specified time period. |
Example Response
{
"stat": "OK",
"response": [{
"maxtime": 1352880416,
"mintime": 1350288416,
"telephony_credits_used": 30
}]
}
Retrieve counts of authentication attempts for a given time period, broken down by result.
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/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 or mintime is after the maxtime .
|
Response Format
Key | Value | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
mintime
|
UNIX timestamp for the beginning of the report period. | ||||||||||
maxtime
|
UNIX timestamp for the end of the report period. | ||||||||||
authentication_attempts
|
Number of authentication attempts during the specified time period, broken down by result:
|
Example Response
{
"stat": "OK",
"response": [{
"authentication_attempts": {
"ERROR": 0,
"FAILURE": 1,
"FRAUD": 1,
"SUCCESS": 50
},
"maxtime": 1352880416,
"mintime": 1350288416
}]
}
Retrieve counts of users with authentication attempts for a given time period, broken down by result. Each count is the number of users who had at least one authentication attempt ending with that result.
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/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 or mintime is after the maxtime .
|
Response Format
Key | Value |
---|---|
mintime
|
UNIX timestamp for the beginning of the report period. |
maxtime
|
UNIX timestamp for the end of the report period. |
user_authentication_attempts
|
Number of users with authentication attempts during the specified time period, broken down by result. Refer to Authentication Attempts Report for a list of result types and their meanings. |
Example Response
{
"stat": "OK",
"response": [{
"maxtime": 1352880416,
"mintime": 1350288416,
"user_authentication_attempts": {
"ERROR": 0,
"FAILURE": 1,
"FRAUD": 1,
"SUCCESS": 10
}
}]
}
Need some help? Take a look at our Admin API Knowledge Base articles or Community discussions. For further assistance, contact Support.