Duo Admin API v1 (Legacy)

Overview

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

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

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

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

About Admin API Version 1

We have started implementing v2 and v3 handlers for endpoints. In these cases, the API v1 handlers listed on this page remain supported, but will be deprecated in the future. These endpoints may not receive updates. We encourage use of the most current endpoints where available and recommend migrating existing API implementations to the v2 or v3 handlers.

Admin API endpoints with v2 or v3 handlers implemented have their v1 handlers classified as legacy. Endpoints with only v1 handlers are considered most current and aren't legacy.

About the Admin API

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

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

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

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

First Steps

Role required: Owner

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

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

3. Locate the entry for Admin API in the applications list. Click Protect to the far-right to configure the application and get your integration key, secret key, and API hostname. You'll need this information to complete your setup. See Protecting Applications for more information about protecting applications with Duo and additional application options.

   Treat your secret key like a password

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

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

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

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

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

API Clients

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

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

API Details

Base URL

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

Methods always use HTTPS. Unsecured HTTP is not supported.

Request Format

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

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

Send parameters for POST requests in the body as URL-encoded key-value pairs (the same request format used by browsers to submit form data).

The header "Content-Type: application/x-www-form-urlencoded" must also be present.

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

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

Response Format

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

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

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

Values are returned as strings unless otherwise documented.

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

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

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

Response Paging

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

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

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

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

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

Paging Metadata Examples:

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

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

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

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

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

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

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

Authentication

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

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

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

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

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

GET requests also use this five-line format:

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

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

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

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

Separate HTTP request header lines with CRLF newlines.

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

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

import base64, email, hmac, hashlib, urllib

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

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

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

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

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

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

Groups

Get Group Info

The v1 groups endpoint limits the response to the first 4,000 group members. Requires "Grant resource - Read" API permission.

GET /admin/v1/groups/[group_id]

Parameters

This API endpoint has no parameters.

Response Codes

Response Format

Example Response

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

Integrations

Retrieve Integrations

Returns a paged list of integrations. To fetch all results, call repeatedly with the offset parameter as long as the result metadata has a next_offset value. This v1 API endpoint cannot retrieve Duo Single Sign-On applications and returns integrations' secret keys in plain text. Requires "Grant resource - Read" API permission.

GET /admin/v1/integrations

Parameters

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

This API endpoint has no additional parameters.

Response Codes

Response Format

Example Response

{
  "metadata": {
    "total_objects": 2
  },
  "response": [
    {
      "adminapi_admins": 0,
      "adminapi_admins_read": 0,
      "adminapi_allow_to_set_permissions": 0,
      "adminapi_info": 0,
      "adminapi_integrations": 0,
      "adminapi_read_log": 0,
      "adminapi_read_resource": 0,
      "adminapi_settings": 0,
      "adminapi_write_resource": 0,
      "enroll_policy": "",
      "frameless_auth_prompt_enabled": 1,
      "greeting": "Welcome to Duo.",
      "groups_allowed": [],
      "integration_key": "DIRWIH0ZZPV4G88B37VQ",
      "ip_whitelist": [],
      "ip_whitelist_enroll_policy": "",
      "name": "Web Application",
      "notes": "",
      "policy_key": "POHSLA8SP00LABDAD98Y",
      "prompt_v4_enabled": 1,
      "secret_key": "QO4ZLqQVRIOZYkHfdPDORfcNf8LeXIbCWwHazY7",
      "self_service_allowed": false,
      "trusted_device_days": 0,
      "type": "websdk",
      "username_normalization_policy": "None"
    },
    {
      "adminapi_admins": 0,
      "adminapi_admins_read": 0,
      "adminapi_allow_to_set_permissions": 0,
      "adminapi_info": 0,
      "adminapi_integrations": 0,
      "adminapi_read_log": 1,
      "adminapi_read_resource": 0,
      "adminapi_settings": 0,
      "adminapi_write_resource": 0,
      "enroll_policy": "",
      "greeting": "Welcome to Duo.",
      "groups_allowed": [],
      "integration_key": "DIRWIH0ZZPV4GJ05H7VQ",
      "name": "Admin API",
      "networks_for_api_access": "",
      "notes": "",
      "secret_key": "QO4ZLqQVRIOZYkHfdPDORj05h8LeXIbCWwHazY7",
      "self_service_allowed": false,
      "type": "adminapi",
      "username_normalization_policy": "None"
    }
  ]
  "stat": "OK"
}

Create Integration

Create a new integration. The new integration key and secret key are randomly generated and returned in the response. This v1 API endpoint cannot create Duo Single Sign-On applications and returns the integration's secret key in plain text. Requires "Grant applications" API permission.

POST /admin/v1/integrations

Parameters

Response Codes

Response Format

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

Example Response

Same as Retrieve Integration by Integration Key.

Retrieve Integration by Integration Key

Return the single integration with integration_key. This v1 API endpoint cannot retrieve Duo Single Sign-On applications and returns the integration's secret key in plain text. Requires "Grant applications" API permission.

GET /admin/v1/integrations/[integration_key]

Parameters

This API endpoint has no parameters.

Response Codes

Response Format

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

Example Response

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

Modify Integration

Change the name, greeting, and/or notes of the integration with integration key integration_key, or reset its secret key. When modifying an Admin API integration permissions can also be added or removed. This v1 API endpoint cannot modifyDuo Single Sign-On applications and returns the integration's secret key in plain text. Requires "Grant applications" API permission.

POST /admin/v1/integrations/[integration_key]

Parameters

Response Codes

Response Format

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

Example Response

Same as Retrieve Integration by Integration Key.

Delete Integration

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

DELETE /admin/v1/integrations/[integration_key]

Parameters

This API endpoint has no parameters.

Response Codes

Response Format

Empty string.

Example Response

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

Logs

Authentication Logs

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

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

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

We recommend requesting logs no more than once per minute.

GET /admin/v1/logs/authentication

Parameters

Response Codes

Response Format

Example Response

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

Telephony Logs

The v2 telephony logs endpoint provides new querying capabilities and contextual information for events unavailable in the legacy v1 handler. Consider migrating to the new handler.

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

We recommend requesting logs no more than once per minute.

GET /admin/v1/logs/telephony

Parameters

Response Codes

Response Format

Example Response

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