Duo Auth API

Overview

Duo Auth API is available to paying Duo Premier, Duo Advantage, and Duo Essentials plan customers, Duo Free, and trial accounts. Learn how to sign up for a Duo account and receive a free 30-day Duo Advantage trial.

The Auth API lets developers integrate with Duo Security's platform at a low level. The API has methods for verifying Duo service connectivity and integration info, retrieving the enrollment status and available authentication devices for a user, and performing authentication.

Developers can add Duo two-factor authentication into existing applications that already have a method for primary authentication.

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

About the Auth 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. 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

Before starting:

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

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

3. Locate the entry for Auth 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!

Review the API Details to see how to construct your first API request. Adding Duo requires some understanding of your application's language and authentication process.

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)

Endpoints

/ping

The /ping endpoint acts as a "liveness check" that can be called to verify that Duo is up before trying to call other Auth API endpoints. Unlike the other endpoints, this one does not have to be signed with the Authorization header.

This endpoint is also suitable for use with Duo's v2 Web SDK to verify that Duo's service is responding before initializing frame authentication.

GET /auth/v2/ping

Parameters

None.

Response Codes

Response Format

Example Response

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

/check

The /check endpoint can be called to verify that the Auth API integration and secret keys are valid, and that the signature is being generated properly.

This endpoint is also suitable for use with Duo's v2 Web SDK to verify integration information before initializing frame authentication.

GET /auth/v2/check

Parameters

None required.

Response Codes

Response Format

Example Response

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

/logo

The /logo endpoint provides a programmatic way to retrieve your stored logo.

GET /auth/v2/logo

Parameters

None required.

Response Codes

Response Format

On success, the response body is Content-Type image/png, containing the logo.

On failure, the response is the standard error JSON.

/enroll

The /enroll endpoint provides a programmatic way to enroll new users with Duo two-factor authentication. It creates the user in Duo and returns a code (as a QR code) that Duo Mobile can scan with its built-in camera. Scanning the QR code adds the user's account to the app so that they receive and respond to Duo Push login requests. This endpoint may be limited by an effective new user policy. For example, if an Auth API application has an effective "New User policy" set to Deny access, you will not be able to use this enrollment endpoint, and will receive a deny response instead of an enrollment link.

POST /auth/v2/enroll

Parameters

Response Codes

Response Format

Example Response

{
  "stat": "OK",
  "response": {
    "activation_barcode": "https://api-abcd1234.duosecurity.com/frame/qr?value=8LIRa5danrICkhHtkLxi-cKLu2DWzDYCmBwBHY2YzW5ZYnYaRxA",
    "activation_code": "duo://8LIRa5danrICkhHtkLxi-cKLu2DWzDYCmBwBHY2YzW5ZYnYaRxA",
    "activation_url": "https://m-abcd1234.duosecurity.com/activate/4n0dwXOE5YZio2VCkied",
    "expiration": 1357020061,
    "user_id": "DU94SWSN4ADHHJHF2HXT",
    "username": "mscott"
  }
}

If a new user policy which denies access to unenrolled users was effective on the Auth API application:

{
  "stat": "FAIL",
  "message": "Access is not allowed because you are not enrolled in Duo. Please contact your organization's IT help desk."
}

/enroll_status

The /enroll_status endpoint checks whether a user has completed enrollment. This endpoint may be limited by an effective new user policy. For example, if an Auth API application has an effective "New User policy" set to Deny access, you will not be able to use this enrollment endpoint, and will receive a deny response instead of an enrollment link.

POST /auth/v2/enroll_status

Parameters

Response Codes

Response Format

One of the following strings:

Example Response

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

If a new user policy which denies access to unenrolled users was effective on the Auth API application:

{
  "stat": "FAIL",
  "message": "Access is not allowed because you are not enrolled in Duo. Please contact your organization's IT help desk."
}

/preauth

The /preauth endpoint determines whether a user is authorized to log in, and (if so) returns the user's available authentication factors.

POST /auth/v2/preauth

Parameters

Response Codes

Response Format

Example Responses

If result was "auth":

{
  "stat": "OK",
  "response": {
    "devices": [
      {
        "capabilities": [
            "auto",
            "push",
            "sms",
            "phone",
            "mobile_otp"
        ],
        "device": "DPFZRS9FB0D46QFTM891",
        "display_name": "iOS (XXX-XXX-0100)",
        "name": "",
        "number": "XXX-XXX-0100",
        "type": "phone"
      },
      {
        "device": "DHEKH0JJIYC1LX3AZWO4",
        "name": "0",
        "type": "token"

      }
    ],
    "result": "auth",
    "status_msg": "Account is active"
  }
}

If result was "auth" and client_supports_verified_push=1:

{
  "stat": "OK",
  "response": {
    "devices": [
      {
        "capabilities": [
            "auto",
            "push",
            "sms",
            "phone",
            "mobile_otp"
        ],
        "device": "DPFZRS9FB0D46QFTM891",
        "display_name": "iOS (XXX-XXX-0100)",
        "name": "",
        "number": "XXX-XXX-0100",
        "type": "phone"
      },
      {
        "device": "DHEKH0JJIYC1LX3AZWO4",
        "name": "0",
        "type": "token"

      }
    ],
    "expiration": 1710428517,
    "result": "auth",
    "status_msg": "Account is active",
    "txid": "7b333558-f3ff-4fe9-8200-f43a8d2d2f29",
    "verification_code": "867"
  }
}

If result was "enroll":

{
  "stat": "OK",
  "response": {
    "enroll_portal_url": "https://api-abcd1234.duosecurity.com/portal?code=48bac5d9393fb2c2&akey=DIXXXXXXXXXXXXXXXXXX",
    "result": "enroll",
    "status_msg": "Enroll an authentication device to proceed"
  }
}

If the result was "allow" because the request included a valid trusted_device_token:

{
  "stat": "OK",
  "response": {
        "result": "allow",
        "status_msg": "Device is trusted."
  },
}

/auth

The /auth endpoint performs second-factor authentication for a user by sending a push notification to the user's smartphone app, verifying a passcode, or placing a phone call. It is also used to send the user a new batch of passcodes via SMS.

POST /auth/v2/auth

Parameters

Additionally, you will need to pass some factor-specific parameters depending on the authentication method.

Duo Push or Verified Duo Push

Passcode

Phone callback

Sending new SMS passcodes

The response will be returned in the container format described above. For successful responses, the payload will contain the following key/value pairs:

Response Codes

Response formats

If async was not enabled:

If async was enabled:

Example Responses

If async was not enabled and the auth attempt succeeded:

{
  "stat": "OK",
  "response": {
    "result": "allow",
    "status": "allow",
    "status_msg": "Success. Logging you in..."
  }
}

If async was not enabled and the auth attempt failed due to factor restriction as a result of Risk-based Factor Selection policy:

{
  "stat": "OK",
  "response": {
        "result": "deny",
        "status": "deny",
        "status_msg": "Selected number is restricted from Duo Push authentication"
  },
}

If async was enabled:

{
  "stat": "OK",
  "response": {
    "txid": "45f7c92b-f45f-4862-8545-e0f58e78075a"
  }
}

If async was not enabled and a Remembered Devices per-application policy was effective on the Auth API application:

{
  "stat": "OK",
  "response": {
        "result": "allow",
        "status": "allow",
        "status_msg": "Success. Logging you in...",
        "trusted_device_token": "REkxSzP00Ld4ddEVTRZOUlYMEl8RFVVQkdJ05HwUldRRThJR1VTNE0=||1627133735|8356ef7779bb0ec4c28ca9b04dc50493c4d2e05e"
  },
}

/auth_status

The /auth_status endpoint "long-polls" for the next status update from the authentication process for a given transaction. That is to say, if no status update is available at the time the request is sent, it will wait until there is an update before returning a response.

GET /auth/v2/auth_status

Parameters

Response Codes

Response Format

Example Response for Duo Push:

{
  "stat": "OK",
  "response": {
    "result": "waiting",
    "status": "pushed",
    "status_msg": "Pushed a login request to your phone..."
  }
}

Example Response for Verified Duo Push:

{
  "stat": "OK",
  "response": {
    "result": "waiting",
    "status": "pushed",
    "status_msg": "Please enter verification code 074 into Duo Mobile..."
  }
}

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: ?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 something like this: https://api-XXXXXXXX.duosecurity.com/admin/v1/users?realname=First%20Last&username=root (substituting the actual API method path and parameters used in your request).

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:

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
/auth/v2/auth
device=auto&factor=push&hostname=wks01&ipaddr=10.2.3.4&username=narroway

GET requests also use this five-line format (note the blank line as this request has no parameters):

Tue, 21 Aug 2012 17:29:18 -0000
GET
api-xxxxxxxx.duosecurity.com
/auth/v2/check
 

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/auth/v2/auth, using DIWJ8X6AEYOR5OMC6TQ1 as the integration key and Zh5eGmUq9zpfQnyUIu5OL9iWoMMv5ZNmk3zLJ4Ep as the secret key:

Date: Tue, 21 Aug 2012 17:29:18 -0000
Authorization: Basic RElXSjhYNkFFWU9SNU9NQzZUUTE6NGUxMzY2MGVmMGEwZTQ5MWFhNzg2ZGNhZmM2MDgwMjU0NzFkOTg5Nw==
Host: api-XXXXXXXX.duosecurity.com
Content-Length: 92
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)}

Troubleshooting

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

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.