Skip navigation
Documentation

Admin API

Contents

Please contact us if you would like access to this API.

The Admin API provides programmatic access to the administrative functionality of Duo Security's two-factor authentication platform.

Overview

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

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

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

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.

Please note that all Unix timestamps are in seconds.

First Steps

  1. Sign up for a Duo account.
  2. Log in to the Duo Admin Panel and navigate to Applications.
  3. Click Protect an Application and locate Admin API in the applications list. Click Protect this Application to get your integration key, secret key, and API hostname. (See Getting Started for help.) Note that only administrators with the Owner role can create or modify an Admin API application in the Duo Admin Panel.

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

Connectivity Requirements

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.

Users

Retrieve Users

Returns a list of users. 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

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
user_id The user’s ID.
username The user’s username.
realname The user’s real name.
email The user’s email address.
status

The user’s status. One of:

Status Description
“active” The user must complete secondary authentication.
“bypass” The user will bypass secondary authentication after completing primary authentication.
“disabled” The user will not be able to log in.
“locked out” The user has been automatically locked out due to excessive authentication attempts.

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.

groups List of groups to which this user belongs.
last_login The last time this user logged in, as a UNIX timestamp, or “null” if the user has not logged in.
notes Notes about this user. Will be seen in the Duo Administrative interface.
phones A list of phones that this user can use.
tokens A list of tokens that this user can use.

Example Response

{
  "stat": "OK",
  "response": [{
    "user_id": "DU3RP9I2WOC59VZX672N",
    "username": "jsmith",
    "realname": "Joe Smith",
    "email": "jsmith@example.com",
    "status": "active",
    "groups": [{
      "desc": "People with hardware tokens",
      "name": "token_users"
    }],
    "last_login": 1343921403,
    "notes": "",
    "phones": [{
      "phone_id": "DPFZRS9FB0D46QFTM899",
      "number": "+15555550100",
      "extension": "",
      "name": "",
      "postdelay": null,
      "predelay": null,
      "type": "Mobile",
      "capabilities": [
        "sms",
        "phone",
        "push"
      ],
      "platform": "Apple iOS",
      "activated": false,
      "sms_passcodes_sent": false
    }],
    "tokens": [{
      "serial": "0",
      "token_id": "DHIZ34ALBA2445ND4AI2",
      "type": "d1"
    }]
  }]
}

Create User

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.
realname Optional The real name of this user.
email Optional The email address of this user.
status Optional The user’s status. One of:
Status Description
“active” The user must complete secondary authentication. This is the default value.
“bypass” The user will bypass secondary authentication after completing primary authentication.
“disabled” The user will not be able to log in.
notes Optional An optional description or notes field. Can be viewed in the Admin Panel.

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 a single object. Refer to Retrieve Users for an explanation of the object’s keys.

Example Response

{
  "stat": "OK",
  "response": {
    "user_id": "DU3RP9I2WOC59VZX672N",
    "username": "jsmith",
    "realname": "Joe Smith",
    "email": "jsmith@example.com",
    "status": "active",
    "groups": [{
      "desc": "People with hardware tokens",
      "name": "token_users"
    }],
    "last_login": 1343921403,
    "notes": "",
    "phones": [{
      "phone_id": "DPFZRS9FB0D46QFTM899",
      "number": "+15555550100",
      "extension": "",
      "postdelay": null,
      "predelay": null,
      "type": "Mobile",
      "capabilities": [
        "sms",
        "phone",
        "push"
      ],
      "platform": "Apple iOS",
      "activated": false,
      "sms_passcodes_sent": false
    }],
    "tokens": [{
      "serial": "0",
      "token_id": "DHIZ34ALBA2445ND4AI2",
      "type": "d1"
    }]
  }
}

Retrieve User by ID

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 Create User.

Modify User

Change the username, 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.
realname Optional The new real 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.

Response Codes

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

Response Format

Same as Retrieve Users.

Example Response

Same as Retrieve User by ID.

Delete User

Delete the user with ID user_id from the system.

DELETE /admin/v1/users/[user_id]

Parameters

None.

Response Codes

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

Response Format

Empty string.

Example Response

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

Enroll User

Enroll a user with user name username and email address email and send them an enrollment email that expires after valid_secs seconds.

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

Get Bypass Codes for User

Clear all existing bypass codes for the user with ID user_id and return a list of count newly generated bypass codes, or specify codes that expire after valid_secs seconds, or reuse_count uses.

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.
404 No user was found with the given user_id.

Response Format

List of strings.

Example Response

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

Retrieve Groups by User ID

Returns a list of groups associated with the user with ID user_id.

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

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 Group with User

Associate a group with the user with ID user_id.

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 “”.
404 Nonexistent user_id.
400 Invalid or missing parameters, or nonexistent group_id.

Response Format

Empty string.

Example Response

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

Disassociate Group from User

Disassociate a group from the user with ID user_id. This method will return 200 if the group was found or if no such group exists.

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

Parameters

None.

Response Codes

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

Response Format

Empty string.

Example Response

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

Retrieve Phones by User ID

Returns a list of phones associated with the user with ID user_id.

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

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"
    ],
    "extension": "",
    "name": "",
    "number": "+15035550102",
    "phone_id": "DPFZRS9FB0D46QFTM890",
    "platform": "Apple iOS",
    "postdelay": null,
    "predelay": null,
    "sms_passcodes_sent": false,
    "type": "Mobile"
  },
  {
    "activated": false,
    "capabilities": [
      "phone"
    ].
    "extension": "",
    "name": "",
    "number": "+15035550103",
    "phone_id": "DPFZRS9FB0D46QFTM891",
    "platform": "Unknown",
    "postdelay": null,
    "predelay": null,
    "sms_passcodes_sent": false,
    "type": "Landline"
  }]
}

Associate Phone with User

Associate a phone with the user with ID user_id.

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 “”.
404 Nonexistent user_id.
400 Invalid or missing parameters, or nonexistent phone_id.

Response Format

Empty string.

Example Response

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

Disassociate Phone from User

Disassociate a phone from the user with ID user_id. This method will return 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": ""
}

Retrieve Hardware Tokens by User ID

Returns a list of hardware tokens associated with the user with ID user_id.

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

Parameters

None.

Response Codes

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

Response Format

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

Example Response

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

Associate Hardware Token with User

Associate a hardware token with the user with ID user_id.

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 “”.
404 Nonexistent user_id.
400 Invalid or missing parameters, token_id already in use by a different user, or nonexistent token_id.

Response Format

Empty string.

Example Response

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

Disassociate Hardware Token from User

Disassociate a hardware token from the user with ID user_id. This method will return 200 if the hardware token was found or if no such hardware token exists.

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": ""
}

Groups

Retrieve Groups

Returns a list of groups.

GET /admin/v1/groups

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:
Status Description
“active” The users in the group must complete secondary authentication.
“bypass” The users in the group will bypass secondary authentication after completing primary authentication.
“disabled” The users in the group will not be able to authenticate.

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 Group

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",
    "name": "Example Group",
    "push_enabled": true,
    "sms_enabled": false,
    "status": "active",
    "voice_enabled": true,
    "mobile_otp_enabled": true
  },
  "stat": "OK"
}

Get Group Info

Retrieve information about a group.

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 Group

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.
404 Group with given ID was not found.
400 Invalid parameters.

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 Group

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

Phones

Retrieve Phones

Returns a list of phones. 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

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

Response Codes

Response Meaning
200 Success.
400 Invalid number.

Response Format

Key Value
activated Has this phone been activated for Duo Mobile yet? Either “true” or “false”.
capabilities List of strings, each a factor that can be used with the device.
Capability Meaning
push The device is activated for Duo Push.
phone The device can receive phone calls.
sms The device can receive batches of SMS passcodes.
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 fingerprint verification. One of: “Configured”, “Disabled”, or “Unknown”. Blank for other platforms.

This information is available to Duo Beyond and Duo Access plan customers.

name Free-form label for the phone.
number The phone number.
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”.
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",
    "name": "",
    "number": "+15555550100",
    "phone_id": "DPFZRS9FB0D46QFTM899",
    "platform": "Google Android",
    "postdelay": "",
    "predelay": "",
    "screenlock": "Locked",
    "sms_passcodes_sent": false,
    "type": "Mobile",
    "users": [{
      "email": "jsmith@example.com",
      "last_login": 1474399627,
      "notes": "",
      "realname": "Joe Smith",
      "status": "active",
      "user_id": "DUJZ2U4L80HT45MQ4EOQ",
      "username": "jsmith"
    }]
  }]
}

Create Phone

Create a new phone with the specified phone number. All other parameters are optional.

POST /admin/v1/phones

Parameters

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

Response Codes

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

Response Format

Same as Retrieve Phone by ID.

Example Response

Same as Retrieve Phone by ID.

Retrieve Phone by ID

Return the single phone with phone_id.

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": {
    "phone_id": "DPFZRS9FB0D46QFTM899",
    "number": "+15555550100",
    "name": "",
    "extension": "",
    "postdelay": null,
    "predelay": null,
    "type": "Mobile",
    "capabilities": [
      "sms",
      "phone",
      "push"
    ],
    "platform": "Apple iOS",
    "activated": false,
    "sms_passcodes_sent": false,
    "users": [{
      "user_id": "DUJZ2U4L80HT45MQ4EOQ",
      "username": "jsmith",
      "realname": "Joe Smith",
      "email": "jsmith@example.com",
      "status": "active",
      "last_login": 1343921403,
      "notes": ""
    }]
  }
}

Modify Phone

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 Phone

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": ""
}

Create Activation Code

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

Send Activation Code via SMS

Generate a Duo Mobile activation code and send it to the phone via SMS, optionally sending an additional message with a URL to install Duo Mobile. This method will fail if the phone’s type or platform are Unknown.

SMS Size Limits

The recommended maximum length for activation_msg and installation_msg is 80 characters.

Activation and installation SMS messages are limited to 160 characters or less. If providing custom text, please make sure to leave enough room for a URL to be sent in the same message. The exact length available for custom text varies depending on the device’s platform and whether international characters were used. Activation URLs are typically about 60 characters long. Installation URLs are between 50 and 75 characters long.

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

Parameters

Parameter Required? Description
valid_secs Optional The number of seconds this activation code 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 Installation URL via SMS

Send a message via SMS describing how to install Duo Mobile. This method will fail if the phone’s type or platform are Unknown.

SMS Size Limits

The recommended maximum length for installation_msg is 80 characters.

Installation SMS messages are limited to 160 characters or less. If providing custom text, please make sure to leave enough room for a URL to be sent in the same message. The exact length available for custom text varies depending on the device’s platform and whether international characters were used. Installation URLs are between 50 and 75 characters long.

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

Parameters

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

Response Codes

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

Response Format

Key Value
installation_msg The text of the installation message.

Example Response

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

Send Passcodes via SMS

Generate a new batch of SMS passcodes send them to the phone in a single SMS message.

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

Parameters

None.

Response Codes

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

Response Format

Empty string.

Example Response

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

Tokens

Retrieve Hardware Tokens

Returns a list of hardware tokens. 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

Parameter Required? Description
type Optional*

Specify a type and serial number to look up a single hardware token. One of:

Type Description
“h6” HOTP-6 hardware token
“h8” HOTP-8 hardware token
“yk” YubiKey AES hardware token
“d1” Duo-D100 hardware token

* This option is required if serial is present.

serial Optional*

The serial number of the hardware token.

* This option is required if type is present.

Response Codes

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

Response Format

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

Example Response

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

Create Hardware Token

Create a new hardware token.

POST /admin/v1/tokens

Parameters

Parameter Required? Description
type Required The type of hardware token. See Retrieve Hardware Tokens for a list of possible values.
serial Required The serial number of the token (maximum length 128 characters).
secret Optional The HOTP secret. This parameter is required for HOTP-6 and HOTP-8 hardware tokens.
counter Optional Initial value for the HOTP counter. Default: 0. This parameter is only valid for HOTP-6 and HOTP-8 hardware tokens.
private_id Optional The YubiKey private ID. This parameter is required for YubiKey hardware tokens.
aes_key Optional The YubiKey AES key. This parameter is required for YubiKey hardware tokens.

Response Codes

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

Response Format

Same as Retrieve Hardware Tokens.

Example Response

Same as Retrieve Hardware Token by ID.

Retrieve Hardware Token by ID

Return the single hardware token with token_id.

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",
      "realname": "Joe Smith",
      "email": "jsmith@example.com",
      "status": "active",
      "last_login": 1343921403,
      "notes": ""
    }]
  }
}

Resync Hardware Token

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

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

Parameters

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

Response Codes

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

Response Format

Empty string.

Example Response

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

Delete Hardware Token

Delete the hardware token with ID token_id from the system.

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": ""
}

Integrations

Retrieve Integrations

Returns a list of integrations.

GET /admin/v1/integrations

Parameters

None.

Response Codes

Response Meaning
200 Success.

Response Format

Key Value
enroll_policy What to do after an unenrolled user passes primary authentication. One of:
Policy Description
“enroll” The user will be prompted to enroll.
“allow” The user will be signed in, skipping any secondary authentication.
“deny” The user will not be able to log in.
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
Type Description
“1password” 1Password
“accountsapi” Accounts API
“adfs” Microsoft ADFS
“adminapi” Admin API
“agadobe_documentcloud” SAML - Adobe Document Cloud
“agasana” SAML - Asana
“agaws” SAML - Amazon Web Services
“agbamboohr” SAML - BambooHR
“agbluejeans” SAML - BlueJeans
“agbomgar” SAML - Bomgar
“agbonusly” SAML - Bonusly
“agbox” SAML - Box
“agcanvas” SAML - Canvas
“agclarizen” SAML - Clarizen
“agcloudlock” SAML - CloudLock
“agconfluence” SAML - Confluence
“agcrashplan” SAML - CrashPlan
“agdatadog” SAML - Datadog
“agdesk” SAML - Desk
“agdocusign” SAML - DocuSign
“agdropbox” SAML - Dropbox
“agegnyte” SAML - Egnyte
“agevernote” SAML - Evernote
“agexpensify” SAML - Expensify
“agfacebook” SAML - Facebook at Work
“agfreshdesk” SAML - Freshdesk
“aggeneric” SAML - Service Provider
“aggithub-enterprise” SAML - GitHub Enterprise
“aggoogle” SAML - Google Apps
“aggotomeeting” SAML - GoToMeeting
“aggreenhouse” SAML - Greenhouse
“aghackerone” SAML - HackerOne
“agheroku” SAML - Heroku
“agintacct” SAML - Intacct
“agjira” SAML - JIRA
“agjitbit” SAML - Jitbit
“aglooker” SAML - Looker
“agmarketo” SAML - Marketo
“agmeraki” SAML - Meraki
“agnamely” SAML - Namely
“agnewrelic” SAML - New Relic
“agoffice365” SAML - Office 365
“agopendns” SAML - OpenDNS
“agpagerduty” SAML - PagerDuty
“agremedyforce” SAML - Remedyforce
“agringcentral” SAML - RingCentral
“agrobin” SAML - Robin
“agsalesforce” SAML - Salesforce
“agsamanage” SAML - Samanage
“agsharefile” SAML - ShareFile
“agsignalsciences” SAML - Signal Sciences
“agslack” SAML - Slack
“agsmartsheet” SAML - Smartsheet
“agstatuspageio” SAML - StatusPage.io
“agsugarcrm” SAML - SugarCRM
“agsumologic” SAML - Sumo Logic
“agsyncplicity” SAML - Syncplicity
“agudemy” SAML - Udemy
“aguservoice” SAML - UserVoice
“agwebex” SAML - Cisco WebEx
“agzendesk” SAML - Zendesk
“agzoom” SAML - Zoom
“array” Array SSL VPN
“authapi” Auth API
“barracuda” Barracuda SSL VPN
“bitium” Bitium
“bomgar” Bomgar
“caradigm” Caradigm
“cas” CAS (Central Authentication Service)
“checkpoint” Check Point VPN
“cisco” Cisco SSL VPN
“ciscoradius” Cisco RADIUS VPN
“citrixcag” Citrix Access Gateway
“citrixns” Citrix NetScaler
“clearpass” Aruba ClearPass
“confluence” Confluence
“cyberark” CyberArk
“dag” Duo Access Gateway
“device-management-portal” Device Management Portal
“drawbridgenetworks” Drawbridge Networks
“drupal” Drupal
“epic” Epic Hyperspace
“f5bigip” F5 BIG-IP APM
“f5firepass” F5 FirePass SSL VPN
“fortinet” Fortinet FortiGate SSL VPN
“greyheller” GreyHeller Firewall
“jira” JIRA
“juniper” Juniper SSL VPN
“juniperuac” Juniper UAC
“keeper” Keeper Security
“labtech” LabTech Software
“lastpass” LastPass
“ldapproxy” LDAP Proxy
“okta” Okta
“onelogin” OneLogin
“openvpn” OpenVPN
“openvpnas” OpenVPN Access Server
“owa” Microsoft OWA
“paloalto” Palo Alto SSL VPN
“pingfederate” PingFederate
“portal” User Portal
“radius” RADIUS
“rdgateway” Microsoft RD Gateway
“rdp” Microsoft RDP
“rdweb” Microsoft RD Web
“resilient” Resilient Systems
“rest” Auth API
“rras” Microsoft RRAS
“sailpoint” SailPoint
“samlidp” SAML IdP
“shibboleth” Shibboleth
“sonicwallsra” SonicWALL SRA SSL VPN
“splunk” Splunk
“thycotic” Thycotic Secret Server
“tmg” Microsoft TMG
“uag” Microsoft UAG
“unix” UNIX Application
“verify” Verify API
“vmwareview” VMWare View
“websdk” Web SDK
“wordpress” WordPress
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:
Type Description
“1password” 1Password
“adfs” Microsoft ADFS
“agadobe_documentcloud” SAML - Adobe Document Cloud
“agasana” SAML - Asana
“agaws” SAML - Amazon Web Services
“agbamboohr” SAML - BambooHR
“agbluejeans” SAML - BlueJeans
“agbomgar” SAML - Bomgar
“agbonusly” SAML - Bonusly
“agbox” SAML - Box
“agcanvas” SAML - Canvas
“agclarizen” SAML - Clarizen
“agcloudlock” SAML - CloudLock
“agconfluence” SAML - Confluence
“agcrashplan” SAML - CrashPlan
“agdatadog” SAML - Datadog
“agdesk” SAML - Desk
“agdocusign” SAML - DocuSign
“agdropbox” SAML - Dropbox
“agegnyte” SAML - Egnyte
“agevernote” SAML - Evernote
“agexpensify” SAML - Expensify
“agfacebook” SAML - Facebook at Work
“agfreshdesk” SAML - Freshdesk
“aggeneric” SAML - Service Provider
“aggithub-enterprise” SAML - GitHub Enterprise
“aggoogle” SAML - Google Apps
“aggotomeeting” SAML - GoToMeeting
“aggreenhouse” SAML - Greenhouse
“aghackerone” SAML - HackerOne
“agheroku” SAML - Heroku
“agintacct” SAML - Intacct
“agjira” SAML - JIRA
“agjitbit” SAML - Jitbit
“aglooker” SAML - Looker
“agmarketo” SAML - Marketo
“agmeraki” SAML - Meraki
“agnamely” SAML - Namely
“agnewrelic” SAML - New Relic
“agoffice365” SAML - Office 365
“agopendns” SAML - OpenDNS
“agpagerduty” SAML - PagerDuty
“agremedyforce” SAML - Remedyforce
“agringcentral” SAML - RingCentral
“agrobin” SAML - Robin
“agsalesforce” SAML - Salesforce
“agsamanage” SAML - Samanage
“agsharefile” SAML - ShareFile
“agsignalsciences” SAML - Signal Sciences
“agslack” SAML - Slack
“agsmartsheet” SAML - Smartsheet
“agstatuspageio” SAML - StatusPage.io
“agsugarcrm” SAML - SugarCRM
“agsumologic” SAML - Sumo Logic
“agsyncplicity” SAML - Syncplicity
“agudemy” SAML - Udemy
“aguservoice” SAML - UserVoice
“agwebex” SAML - Cisco WebEx
“agzendesk” SAML - Zendesk
“agzoom” SAML - Zoom
“array” Array SSL VPN
“authapi” Auth API
“barracuda” Barracuda SSL VPN
“bitium” Bitium
“cas” CAS (Central Authentication Service)
“cisco” Cisco SSL VPN
“citrixcag” Citrix Access Gateway
“citrixns” Citrix NetScaler
“clearpass” Aruba ClearPass
“confluence” Confluence
“dag” Duo Access Gateway
“device-management-portal” Device Management Portal
“drawbridgenetworks” Drawbridge Networks
“drupal” Drupal
“f5bigip” F5 BIG-IP APM
“f5firepass” F5 FirePass SSL VPN
“fortinet” Fortinet FortiGate SSL VPN
“greyheller” GreyHeller Firewall
“jira” JIRA
“juniper” Juniper SSL VPN
“juniperuac” Juniper UAC
“okta” Okta
“onelogin” OneLogin
“owa” Microsoft OWA
“paloalto” Palo Alto SSL VPN
“pingfederate” PingFederate
“rdgateway” Microsoft RD Gateway
“rdweb” Microsoft RD Web
“resilient” Resilient Systems
“rest” Auth API
“shibboleth” Shibboleth
“sonicwallsra” SonicWALL SRA SSL VPN
“splunk” Splunk
“websdk” Web SDK
“wordpress” WordPress
ip_whitelist CSV string of IPs/Ranges from which the second authentication factor will not be required, will be returned as an array. Example: “192.0.2.8,198.51.100.0-198.51.100.20,203.0.113.0/24”. Supported with these integration types:
Type Description
“1password” 1Password
“adfs” Microsoft ADFS
“agadobe_documentcloud” SAML - Adobe Document Cloud
“agasana” SAML - Asana
“agaws” SAML - Amazon Web Services
“agbamboohr” SAML - BambooHR
“agbluejeans” SAML - BlueJeans
“agbomgar” SAML - Bomgar
“agbonusly” SAML - Bonusly
“agbox” SAML - Box
“agcanvas” SAML - Canvas
“agclarizen” SAML - Clarizen
“agcloudlock” SAML - CloudLock
“agconfluence” SAML - Confluence
“agcrashplan” SAML - CrashPlan
“agdatadog” SAML - Datadog
“agdesk” SAML - Desk
“agdocusign” SAML - DocuSign
“agdropbox” SAML - Dropbox
“agegnyte” SAML - Egnyte
“agevernote” SAML - Evernote
“agexpensify” SAML - Expensify
“agfacebook” SAML - Facebook at Work
“agfreshdesk” SAML - Freshdesk
“aggeneric” SAML - Service Provider
“aggithub-enterprise” SAML - GitHub Enterprise
“aggoogle” SAML - Google Apps
“aggotomeeting” SAML - GoToMeeting
“aggreenhouse” SAML - Greenhouse
“aghackerone” SAML - HackerOne
“agheroku” SAML - Heroku
“agintacct” SAML - Intacct
“agjira” SAML - JIRA
“agjitbit” SAML - Jitbit
“aglooker” SAML - Looker
“agmarketo” SAML - Marketo
“agmeraki” SAML - Meraki
“agnamely” SAML - Namely
“agnewrelic” SAML - New Relic
“agoffice365” SAML - Office 365
“agopendns” SAML - OpenDNS
“agpagerduty” SAML - PagerDuty
“agremedyforce” SAML - Remedyforce
“agringcentral” SAML - RingCentral
“agrobin” SAML - Robin
“agsalesforce” SAML - Salesforce
“agsamanage” SAML - Samanage
“agsharefile” SAML - ShareFile
“agsignalsciences” SAML - Signal Sciences
“agslack” SAML - Slack
“agsmartsheet” SAML - Smartsheet
“agstatuspageio” SAML - StatusPage.io
“agsugarcrm” SAML - SugarCRM
“agsumologic” SAML - Sumo Logic
“agsyncplicity” SAML - Syncplicity
“agudemy” SAML - Udemy
“aguservoice” SAML - UserVoice
“agwebex” SAML - Cisco WebEx
“agzendesk” SAML - Zendesk
“agzoom” SAML - Zoom
“array” Array SSL VPN
“authapi” Auth API
“barracuda” Barracuda SSL VPN
“bitium” Bitium
“caradigm” Caradigm
“cas” CAS (Central Authentication Service)
“cisco” Cisco SSL VPN
“citrixcag” Citrix Access Gateway
“citrixns” Citrix NetScaler
“clearpass” Aruba ClearPass
“confluence” Confluence
“dag” Duo Access Gateway
“device-management-portal” Device Management Portal
“drawbridgenetworks” Drawbridge Networks
“drupal” Drupal
“f5bigip” F5 BIG-IP APM
“f5firepass” F5 FirePass SSL VPN
“fortinet” Fortinet FortiGate SSL VPN
“greyheller” GreyHeller Firewall
“jira” JIRA
“juniper” Juniper SSL VPN
“juniperuac” Juniper UAC
“keeper” Keeper Security
“lastpass” LastPass
“okta” Okta
“onelogin” OneLogin
“owa” Microsoft OWA
“paloalto” Palo Alto SSL VPN
“pingfederate” PingFederate
“rdgateway” Microsoft RD Gateway
“rdp” Microsoft RDP
“rdweb” Microsoft RD Web
“resilient” Resilient Systems
“rest” Auth API
“sailpoint” SailPoint
“shibboleth” Shibboleth
“sonicwallsra” SonicWALL SRA SSL VPN
“splunk” Splunk
“unix” UNIX Application
“websdk” Web SDK
“wordpress” WordPress
ip_whitelist_enroll_policy Policy for handling new users from IPs on the whitelist. One of:
Policy Description
“enforce” The new user will be subject to the enrollment policy (i.e. enroll_policy).
“allow” The new user will be signed in, skipping any policy defined by the enrollment policy.
username_normalization_policy This controls whether or not usernames should be altered before trying to match them to a user account. One of:
Policy Description
“None” The username will be used as is.
“Simple” Both “DOMAIN\username” and “username@example.com” will be normalized to “username” when logging in.

Example Response

{
  "stat": "OK",
  "response": [{
      "enroll_policy": "enroll",
      "greeting": "",
      "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": "Integration for the web server",
      "notes": "",
      "secret_key": "QO4ZLqQVRIOZYkHfdPDORfcNf8LeXIbCWwHazY7o",
      "type": "websdk",
      "trusted_device_days": 0,
      "username_normalization_policy": "None",
  }]
}

Create Integration

Create a new integration. The new integration key and secret key are randomly generated and returned in the response.

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.
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.
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, or integration already exists with the given name.

Response Format

Same as Retrieve Integrations.

Example Response

Same as Retrieve Integration by Integration Key.

Retrieve Integration by Integration Key

Return the single integration with integration_key.

GET /admin/v1/integrations/[integration_key]

Parameters

None.

Response Codes

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

Response Format

Same as Retrieve Integrations.

Example Response

{
  "stat": "OK",
  "response": {
      "enroll_policy": "enroll",
      "greeting": "",
      "groups_allowed": [],
      "integration_key": "DIRWIH0ZZPV4G88B37VQ",
      "name": "Integration for the web server",
      "notes": "",
      "secret_key": "QO4ZLqQVRIOZYkHfdPDORfcNf8LeXIbCWwHazY7o",
      "type": "websdk",
  }
}

Modify Integration

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

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

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

Response Format

Same as Retrieve Integrations.

Example Response

Same as Retrieve Integration by Integration Key.

Delete Integration

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

DELETE /admin/v1/integrations/[integration_key]

Parameters

None.

Response Codes

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

Response Format

Empty string.

Example Response

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

Endpoints

Retrieve Endpoints

Returns a list of endpoints.

GET /admin/v1/endpoints

Parameters

None.

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 was last used for access or authentication, as a Unix timestamp.
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.
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
        }],
        "email": "ejennings@example.com",
        "epkey": "EP18JX1A10AB102M2T2X",
        "model": "",
        "os_family": "Mac OS X",
        "os_version": "10.11.5",
        "type": "",
        "username": "ejennings"
    },
    {
        "browsers": [{
            {
                "browser_family": "Mobile Safari",
                "browser_version": "9.0",
                "flash_version": "uninstalled",
                "java_version": "uninstalled"
                }],
        "email": "",
        "epkey": "EP65MWZWXA10AB1027TQ",
        "model": "iPhone",
        "os_family": "iOS",
        "os_version": "9.3.3",
        "type": "",
        "username": "mhanson"
    }],
    "stat": "OK"
}

Retrieve Endpoint by ID

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
        }],
        "email": "amoss@example.com",
        "epkey": "EP18JX1A10AB102M2T2X",
        "model": "",
        "os_family": "Mac OS X",
        "os_version": "10.11.6",
        "type": "",
        "username": "amoss"
    }],
    "stat": "OK"
}

Administrators

Retrieve Administrators

Returns a list of administrators.

GET /admin/v1/admins

Parameters

None.

Response Codes

Response Meaning
200 Success.

Response Format

Key Value
name The administrator’s real name.
admin_id The administrator’s ID.
email The administrator’s email address.
phone The administrator’s phone number.
last_login The last time this administrator logged in, as a UNIX timestamp, or “null” if the administrator has not logged in.
role The administrator’s role. Only present in the response if the customer edition includes the Administrative Roles feature.

Example Response

{
  "stat": "OK",
  "response": [{
    "name": "Rachael Scott",
    "admin_id": "DEVKWVBJA7LO95OIBIS3",
    "email": "rscott@example.com",
    "last_login": 1343921403,
    "phone": "+15035551000",
    "role": "Owner"
  }]
}

Create Administrator

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 6 characters long.
name Required Name for the new administrator.
phone Required Phone number for the new administrator.
role Optional The administrator’s role. One of: “Owner”, “Administrator”, “Integration Manager”, “User Manager”, “Help Desk”, “Billing”, or “Read-only”. If not specified, the default role is “Owner”. Roles other than “Owner” are effective only if the customer edition includes the Administrative Roles feature.

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

Same as Retrieve Administrator by ID.

Retrieve Administrator by ID

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": {
    "name": "Rachael Scott",
    "admin_id": "DEVKWVBJA7LO95OIBIS3",
    "email": "rscott@example.com",
    "phone": "+15035551000",
    "last_login": 1343921403,
    "role": "Owner"
  }
}

Modify Administrator

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 present it cannot be empty.
password Optional New password for the administrator. If this parameter is present it must be at least six characters.
role Optional New role for the administrator. One of: “Owner”, “Administrator”, “Integration Manager”, “User Manager”, “Help Desk”, “Billing”, or “Read-only”. Roles other than “Owner” are effective only if the customer edition includes the Administrative Roles feature.

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 Administrator

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": ""
}

Reset Administrator Authentication Attempts

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

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 Administrator Activation Link

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

POST /admin/v1/admins/activate

Parameters

Parameter Required? Description
email Required Email address for the new administration. Must not already be in use by any other administrator.
send_email Optional If set to “1”, the activation link and an introductory message will be emailed to the new administrator. If set to “0”, no email is sent, and the link is returned to the API method’s caller only. Default: “0”.
valid_days Optional Number of days before the link expires. Default: 7. Maximum days: 31.

Response Codes

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

Response Format

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

Example Response

{
  "response": {
    "code": "g793cfba2b4e8684164c6b8766baad08",
    "email": "example@example.com",
    "email_sent": 0,
    "link": "https://admin-eval.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 Demo Customer.\n\nPlease click on the following link to create the account and fill in the required information:\n\nhttps://admin-eval.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"
}

Logs

Authentication Logs

Returns a list of authentication log events. 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 timestamp of mintime or later. Use mintime+1 to avoid receiving duplicate data.

Response Codes

Response Meaning
200 Success.

Response Format

Key Value
access_device

Browser, plugin, and operating system information for the endpoint used to access the Duo-protected resource. Values present only when the application accessed features Duo’s inline browser prompt.

This information is available to Duo Beyond and Duo Access plan customers.

device Device used to authenticate, if present, otherwise none.
factor The authentication factor. One of: “phone call”, “passcode”, “bypass code”, “sms passcode”, “sms refresh”, or “duo push”.
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”, “Bypass user”, “Trusted device”, “Trusted location”, “Trusted network”, “User Approved”, “Valid passcode”.

If result is “failure” then one of: “Anonymous IP”, “Anomalous push”, “Deny unenrolled user”, “Factor restricted”, “Invalid device”, “Invalid passcode”, “Location restricted”, “Locked out”, “No response”, “No disk encryption”, “No screen lock”, “No Touch ID”, “Platform restricted”, “Rooted device”, “User is disabled”, “User mistake”, 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": "Firefox",
           "browser_version": "41.0",
           "flash_version": "22.0.0.192",
           "java_version": "1.8.0.92",
           "os": "Mac OS X",
           "os_version": "10.11"
      },
      "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",

  }]
}

Administrator Logs

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

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:
Type Description
“ad_sync_begin” AD Sync started
“ad_sync_config_download” AD Sync configuration download
“ad_sync_finish” AD Sync completed
“admin_create” Added administrator
“admin_delete” Deleted administrator
“admin_login” Logged in
“admin_update” Modified administrator
“create_child_customer” Created child customer
“credits_update” Added telephony credits
“customer_update” Modified settings
“delete_child_customer” Deleted child customer
“directory_create” Added directory
“directory_delete” Deleted directory
“directory_groups_update” Modified directory groups
“directory_update” Modified directory
“edition_update” Update edition
“feature_add” Added feature
“feature_delete” Deleted feature
“group_create” Added group
“group_delete” Deleted group
“group_update” Updated group
“hardtoken_create” Created hardware tokens
“hardtoken_delete” Deleted hardware token
“hardtoken_resync” Resynchronized hardware token
“hardtoken_update” Modified hardware token
“integration_create” Added application
“integration_delete” Deleted application
“integration_group_policy_add” Add application group policy
“integration_group_policy_remove” Remove application group policy
“integration_policy_assign” Assign application policy
“integration_policy_unassign” Unassign application policy
“integration_skey_view” Viewed secret key
“integration_update” Modified application
“phone_associate” Associated phone
“phone_create” Added phone
“phone_delete” Deleted phone
“phone_disassociate” Disassociated phone
“phone_update” Modified phone
“policy_create” Added policy
“policy_delete” Deleted policy
“policy_update” Modified policy
“resend_enroll_codes” Resend all enroll codes
“send_enroll_code” Send an enroll code
“u2ftoken_create” Created U2F token
“u2ftoken_delete” Deleted U2F token
“user_bulk_enroll” Bulk enrollment
“user_create” Added user
“user_delete” Deleted user
“user_import” Imported users
“user_pending_delete” Marked user for deletion
“user_restore” Restored deleted user
“user_update” Modified user
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 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.

Example Response

{
  "stat": "OK",
  "response": [{
      "action": "user_update",
      "description": "{\"notes\": \"Joe asked for his nickname to be displayed instead of Joseph.\", \"realname\": \"Joe Smith\"}",
      "object": "jsmith",
      "timestamp": 1346172820,
      "username": "admin"
  }]
}

Telephony Logs

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

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"
  }]
}

Settings

Retrieve Settings

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 his 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: 6.
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: 1000 (unlimited).
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,
      "inactive_user_expiration": 30,
      "keypress_confirm": "#",
      "keypress_fraud": "*",
      "language": "EN",
      "lockout_expire_duration": null,
      "lockout_threshold": 10,
      "log_retention_days": null,
      "minimum_password_length": 6,
      "mobile_otp_enabled": true,
      "name": "Demo Customer",
      "password_requires_lower_alpha": false,
      "password_requires_numeric": false,
      "password_requires_special": false,
      "password_requires_upper_alpha": false,
      "push_enabled": true,
      "sms_batch": 1,
      "sms_enabled": true,
      "sms_expiration": 10,
      "sms_message": "SMS passcodes",
      "sms_refresh": 0,
      "telephony_warning_min": 0,
      "timezone": "UTC",
      "user_telephony_cost_max": 20.0,
      "voice_enabled": true,
  }
}

Modify Settings

Change 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 his 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: 6.
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: 1000 (unlimited).
u2f_enabled Optional If true, users will be able to use authenticate with a U2F device. If false, users will not be able to authenticate with a U2F device. Default: false.

Response Codes

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

Response Format

Same as Retrieve Settings.

Example Response

Same as Retrieve Settings.

Retrieve Duo Mobile Logo

Returns the logo to display in Duo Mobile.

GET /admin/v1/logo

Parameters

None.

Response Codes

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

Response Format

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

Modify Duo Mobile Logo

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

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.

Delete Duo Mobile Logo

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.

Account Info

Retrieve Summary

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

Telephony Credits Used Report

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

Authentication Attempts Report

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:
Result Meaning
“ERROR” An unexpected failure prevented authentication (for example, an invalid telephone number).
“FAILURE” Authentication was denied.
“FRAUD” The attempt ended with a report of fraudulent activity.
“SUCCESS” Authentication was allowed.

Example Response

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

Users with Authentication Attempts Report

Retrieve counts of users with authentication attempts for a given time period, 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
    }
  }]
}

API Details

Base URL

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

Methods always use HTTPS. Unsecured HTTP is not supported.

Request Format

All requests must have “Authorization” and “Date” headers.

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

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

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

Response Format

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

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

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

Values are returned as strings unless otherwise documented.

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

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

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

Response Meaning
200 The request completed successfully.
401 The “Authorization”, “Date”, and/or “Content-Type” headers were missing or invalid.
403

This integration is not authorized for this endpoint or the ikey was created for a different integration type (for example, using an Auth API ikey with Admin API endpoints).

405 The request’s HTTP verb is not valid for this endpoint (for example, POST when only GET is supported).
429 The account has made too many requests of this type recently. Try again later.

Authentication

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

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

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

Component Description Example
date The current time, formatted as RFC 2822. This must be the same string as the “Date” header. Tue, 21 Aug 2012 17:29:18 -0000
method The HTTP method (uppercase) POST
host Your API hostname (lowercase) api-xxxxxxxx.duosecurity.com
path

The specific API method’s path

/admin/v1/users
params The URL-encoded list of key=value pairs, lexicographically sorted by key. These come from the request parameters (the URL query string for GET and DELETE requests or the request body for POST requests). If the request does not have any parameters one must still include a blank line in the string that is signed. Do not encode unreserved characters. Use upper-case hexadecimal digits A through F in escape sequences. realname=First%20Last&username=root

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

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

GET requests also use this five-line format:

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

Lastly, compute the HMAC-SHA1 of this canonical representation, using your Duo 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.

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

Troubleshooting

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

Ready to Get Started?

Sign Up Free