Duo Admin&nbsp;API

Modify Administrative Unit

Change the name, description, assigned administrators, groups, and/or integrations of the administrative unit with admin_unit_id. Requires "Grant administrators" API permission.

POST /admin/v1/administrative_units/[admin_unit_id]

Parameters

Parameter	Required?	Description
`name`	Optional	The new name of the administrative unit. Must be unique amongst all administrative units.
`description`	Optional	An updated description of the administrative unit.
`restrict_by_groups`	Optional	Change whether the administrative unit specifies groups. Default: `false`.
`restrict_by_integrations`	Optional	Change whether the administrative unit specifies integrations. Default: `false`.
`admins`	Optional	One or more `admin_id` values to assign additional administrators to the administrative unit. The administrator user must have `restricted_by_admin_units` set to `true` before attempting to assign them to an administrative unit via the API.
`groups`	Optional	One or more `group_id` values to assign additional groups to the administrative unit.
`integrations`	Optional	One or more `integration_key` values to assign additional integrations to the administrative unit.

Response Codes

Response	Meaning
200	The administrative unit was modified. Also returns unit details.
400	Invalid parameter(s), or an administrative unit with the specified `admin_unit_id` does not exist.

Response Format

Add Administrator to Administrative Unit

Assign the administrator with admin_id to the administrative unit with admin_unit_id. The administrator user must have restricted_by_admin_units set to true before attempting to assign them to an administrative unit via the API. Requires "Grant administrators" API permission.

POST /admin/v1/administrative_units/[admin_unit_id]/admin/[admin_id]

Parameters

This API endpoint has no parameters.

Response Codes

Response	Meaning
200	The administrative unit was modified. Also returns unit details.
400	Invalid `admin_unit_id` or `admin_id`, or the `restricted_by_admin_units` value is `false` for that administrator.

Response Format

Remove Administrator from Administrative Unit

Unassign the administrator with admin_id from the administrative unit with admin_unit_id. The administrator user will still have restricted_by_admin_units set to true, and if the admin is not assigned to any other admin unit they will not be able to view any users or integrations. Be sure to change the value of restricted_by_admin_units to false to permit that admin to view all users and integrations. Requires "Grant administrators" API permission.

DELETE /admin/v1/administrative_units/[admin_unit_id]/admin/[admin_id]

Parameters

This API endpoint has no parameters.

Response Codes

Response	Meaning
200	The administrative unit was modified. Also returns unit details.
400	Invalid `admin_unit_id` or `admin_id`.

Response Format

Add Group to Administrative Unit

Assign the group with group_id to the administrative unit with admin_unit_id. Requires "Grant administrators" API permission.

POST /admin/v1/administrative_units/[admin_unit_id]/group/[group_id]

Parameters

This API endpoint has no parameters.

Response Codes

Response	Meaning
200	The administrative unit was modified. Also returns unit details.
400	Invalid `admin_unit_id` or `group_id`.

Response Format

Remove Group from Administrative Unit

Unassign the group with group_id from the administrative unit with admin_unit_id. Requires "Grant administrators" API permission.

DELETE /admin/v1/administrative_units/[admin_unit_id]/group/[group_id]

Parameters

This API endpoint has no parameters.

Response Codes

Response	Meaning
200	The administrative unit was modified. Also returns unit details.
400	Invalid `admin_unit_id` or `group_id`.

Response Format

Add Integration to Administrative Unit

Assign the integration with integration_key to the administrative unit with admin_unit_id. Requires "Grant administrators" API permission.

POST /admin/v1/administrative_units/[admin_unit_id]/integration/[integration_key]

Parameters

This API endpoint has no parameters.

Response Codes

Response	Meaning
200	The administrative unit was modified. Also returns unit details.
400	Invalid `admin_unit_id` or `integration_key`.

Response Format

Remove Integration from Administrative Unit

Unassign the integration with integration_key from the administrative unit with admin_unit_id. Requires "Grant administrators" API permission.

DELETE /admin/v1/administrative_units/[admin_unit_id]/integration/[integration_key]

Parameters

This API endpoint has no parameters.

Response Codes

Response	Meaning
200	The administrative unit was modified. Also returns unit details.
400	Invalid `admin_unit_id` or `integration_key`.

Response Format

Delete Administrative Unit

Delete the administrative unit with admin_unit_id from the system. Requires "Grant administrators" API permission.

DELETE /admin/v1/administrative_units/[admin_unit_id]

Parameters

This API endpoint has no parameters.

Response Codes

Response	Meaning
200	The administrative unit was deleted or did not exist.

Response Format

Empty string.

Example Response

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

Logs

Authentication Logs

Returns a paged list of authentication log events ranging from the last 180 days up to as recently as two minutes before the API request. To fetch all results, call repeatedly with the next_offset paging parameter as long as the result metadata has next_offset values. Requires "Grant read log" API permission.

There is an intentional two minute delay in availability of new authentications in the API response. Duo operates a large scale distributed system, and this two minute buffer period ensures that calls will return consistent results. Querying for results more recent than two minutes will return as empty.

We recommend requesting logs no more than once per minute.

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

GET or POST /admin/v2/logs/authentication

Parameters

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

Paging Parameter Required? Allow Multiple? Description

limit

Optional

The maximum number of records returned.

Default: 100; Max: 1000

next_offset

Optional

Yes

The offset at which to start record retrieval. This value is provided in the metadata in the form of a 13 character date string in milliseconds and the event txid. Both of these values must be provided when used, separated by a comma.

When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset.

Default: None

Example: next_offset=1547486297000,5bea1c1e-612c-4f1d-b310-75fd31385b15

sort

Optional

The order in which to return records. One of:

Value	Description
`ts:asc`	Return logs in chronological order.
`ts:desc`	Return logs in reverse chronological order.

Parameter Required? Allow Multiple? Description

mintime

Required

Return records that have a 13 character Unix timestamp in milliseconds of mintime or later. This value must be strictly less than maxtime.

Example: 1661022959934

maxtime

Required

Return records that have a 13 character Unix timestamp in milliseconds of maxtime or earlier. This value must be strictly greater than mintime.

Example: 1661022969934

applications

Optional

Yes. Multiple values create an OR query.

An integration's integration_key or the key value for an application returned in the authentication log output.

Default: Return logs for all applications.

users

Optional

Yes. Multiple values create an OR query.

A user's user_id or the key value for a user returned in the authentication log output.

Default: Return logs for all users.

event_types

Optional

Yes. Multiple values create an OR query.

The type of authentication event. One of:

Value	Description
`authentication`	Return events for authentication attempts.
`enrollment`	Return events related to a user completing Duo's inline enrollment.

factors

Optional

Yes. Multiple values create an OR query.

The factor or method used for an authentication attempt. One of:

Value	Description
`duo_push`	Return events where the authentication factor was "Duo Push".
`phone_call`	Return events where the authentication factor was a phone call.
`u2f_token`	Return events where the authentication factor was a U2F token.
`hardware_token`	Return events where the authentication factor was a hardware token passcode.
`bypass_code`	Return events where the authentication factor was a bypass code.
`sms_passcode`	Return events where the authentication factor was an SMS passcode.
`duo_mobile_passcode`	Return events where the authentication factor was a passcode generated by "Duo Mobile".
`yubikey_code`	Return events where the authentication factor was a Yubikey OTP token passcode.
`passcode`	Return events where the authentication factor was a passcode not identified as another known type.
`digipass_go_7_token`	Return events where the authentication factor was a Digipass GO 7 token purchased from Duo.
`WebAuthn Security Key`	Return events where the authentication factor was a FIDO2 security key.
`WebAuthn Chrome Touch ID`	Return events where the authentication factor was Apple Touch ID with the Chrome browser.
`WebAuthn Credential`	Return events where the authentication factor was a WebAuthn authenticator other than a security key or Touch ID.
`not_available`	Return events where the authentication factor is not available.
`sms_refresh`	Return events where the user requested a refresh batch of SMS passcodes.
`remembered_device`	Return events where the authentication factor was the remembered device token from a previous authentication success.
`trusted_network`	Return events where the effective authentication factor was an authorized network.
`trusted_mobile_authenticator`	Return events where the effective authentication factor Duo Mobile Inline Auth on an Android or iOS device.

groups

Optional

Yes. Multiple values create an OR query.

A group's group_id or the key value for a group returned in the authentication log output.

Default: Return logs for all groups.

phone_numbers

Optional

Yes. Multiple values create an OR query.

A phone's number as returned in the authentication log output. If the phone has been given a text name then both are returned in the format name (number).

Default: Return logs for all phone numbers used.

reasons

Optional

Yes. Multiple values create an OR query.

The reason associated with an authentication attempt. One of:

Value	Description
`user_marked_fraud`	Return events where authentication was denied because the end user explicitly marked "fraudulent".
`deny_unenrolled_user`	Return events where authentication was denied because of the following policy: "deny not enrolled users".
`error`	Return events where authentication was denied because of an error.
`locked_out`	Return events generated by users that are locked out.
`user_disabled`	Return events where authentication was denied because the user was disabled.
`user_cancelled`	Return events where authentication was denied because the end user cancelled the request.
`invalid_passcode`	Return events where authentication was denied because the passcode was invalid.
`no_response`	Return events where authentication was denied because there was no response from the user.
`no_keys_pressed`	Return events where authentication was denied because no keys were pressed to accept the auth.
`call_timed_out`	Return events where authentication was denied because the call was not answered or call authentication timed out for an indeterminate reason.
`location_restricted`	Return events where authentication was denied because the end user's location was restricted.
`factor_restricted`	Return events where authentication was denied because the authentication method used was not allowed.
`platform_restricted`	Return events where authentication was denied because the access platform was not allowed.
`version_restricted`	Return events where authentication was denied because the software version was not allowed.
`rooted_device`	Return events where authentication was denied because the approval device was rooted.
`no_screen_lock`	Return events where authentication was denied because the approval device does not have screen lock enabled.
`touch_id_disabled`	Return events where authentication was denied because the approval device's biometrics (fingerprint, Face ID or Touch ID) is disabled.
`no_disk_encryption`	Return events where authentication was denied because the approval device did not have disk encryption enabled.
`anonymous_ip`	Return events where authentication was denied because the authentication request came from an anonymous IP address.
`out_of_date`	Return events where authentication was denied because the software was out of date.
`denied_by_policy`	Return events where authentication was denied because of a policy.
`software_restricted`	Return events where authentication was denied because of software restriction.
`no_duo_certificate_present`	Return events where authentication was denied because there was no Duo certificate present.
`user_provided_invalid_certificate`	Return events where authentication was denied because an invalid management certificate was provided.
`could_not_determine_if_endpoint_was_trusted`	Return events where authentication was denied because it could not be determined if the endpoint was trusted.
`invalid_management_certificate_collection_state`	Return events where authentication was denied because of an invalid management certificate collection state.
`no_referring_hostname_provided`	Return events where authentication was denied because no referring hostname was provided.
`invalid_referring_hostname_provided`	Return events where authentication was denied because an invalid referring hostname was provided.
`no_web_referer_match`	Return events where authentication was denied because an invalid referring hostname did not match an application's hostnames list.
`endpoint_failed_google_verification`	Return events where authentication was denied because the endpoint failed Google verification.
`endpoint_is_not_trusted`	Return events where authentication was denied because the endpoint was not trusted.
`invalid_device`	Return events where authentication was denied because the device was invalid.
`anomalous_push`	Return events where authentication was denied because of an anomalous push.
`endpoint_is_not_in_management_system`	Return events where authentication was denied because the endpoint is not in a management system.
`no_activated_duo_mobile_account`	Return events where authentication was denied because the end user does not have an activated Duo Mobile app account.
`allow_unenrolled_user`	Return events where authentication was successful because of the following policy: "allow not enrolled users".
`bypass_user`	Return events where authentication was successful because a bypass code was used.
`trusted_network`	Return events where authentication was successful because the end user was on a trusted network.
`remembered_device`	Return events where authentication was successful because the end user was on a remembered device.
`trusted_location`	Return events where authentication was successful because the end user was in a trusted location.
`user_approved`	Return events where authentication was successful because the end user approved the authentication request.
`valid_passcode`	Return events where authentication was successful because the end user used a valid passcode.
`allowed_by_policy`	Return events where authentication was successful because of a policy.
`allow_unenrolled_user_on_trusted_network`	Return events where authentication was successful because the unenrolled user's access device was on an authorized network.
`user_not_in_permitted_group`	Return events where authentication was denied because the user did not belong to one of the Permitted Groups specified in the application's settings.

Default: Return logs for any result. Filtering on all values is equivalent to the default.

Note that enrollment events have no associated reason.

results

Optional

Yes. Multiple values create an OR query.

The result of an authentication attempt. One of:

Value	Description
`success`	Return "successful" authentication events.
`denied`	Return "denied" authentication events.
`fraud`	Return "fraudulent" authentication events.

Default: Return logs for any result. Filtering on all values is equivalent to the default.

tokens

Optional

Yes. Multiple values create an OR query.

A WebAuthn security key's webauthnkey or U2F security key's registration_id as returned in the authentication log output.

Default: Return logs for security keys used.

Response Codes

Response	Meaning
200	Success.
400	Invalid or missing parameters or `mintime` is after the `maxtime`.

Response Format

Key Value

access_device

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

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

browser The web browser used for access.

browser_version The browser version.

flash_version The Flash plugin version used, if present, otherwise "uninstalled".

hostname The hostname, if present, otherwise null .

ip The access device's IP address, if present, otherwise null .

is_encryption_enabled Reports the disk encryption state as detected by the Duo Device Health app. One of true, false, or "unknown".

is_firewall_enabled Reports the firewall state as detected by the Duo Device Health app. One of true, false, or "unknown".

is_password_set Reports the system password state as detected by the Duo Device Health app. One of true, false, or "unknown".

java_version The Java plugin version used, if present, otherwise "uninstalled".

location

The GeoIP location of the access device, if available. The response may not include all location parameters.

`city`	The city name.
`country`	The country name. Refer to ISO 3166 for a list of possible countries.
`state`	The state, county, province, or prefecture.

os The device operating system name.

os_version The device operating system version.

security_agents Reports the security agents present on the endpoint as detected by the Duo Device Health app.

adaptive_trust_assessments

Risk-based authentication information. Values present only when the application accessed features Duo's inline browser prompt and has a Duo Risk-Based Authentication policy applied.

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

Type of adaptive trust assessment. One of:

more_secure_auth: Trust assessment information for Risk-Based Factor Selection.

remember_me: Trust assessment information for Risk-Based Remembered Devices.

`features_version`	The feature version for the risk-based authentication trust assessment.
`model_version`	The model version for the risk-based authentication trust assessment.
`policy_enabled`	Denotes if risk-based authentication was enabled by the policy under which the trust assessment was evaluated. One of: `true`, `false`, or `false` (reserved for historical authentication logs that do not have the `policy_enabled` field populated).
`reason`	The reason behind the trust assessment level.
`trust_level`	The trust assessment level. Can be One of: `ERROR`, `LOW`, `NORMAL`, `UNKNOWN`, or `UNSET`.

alias The username alias used to log in. No value if the user logged in with their username instead of a username alias.

application

Information about the application accessed.

`key`	The application's `integration_key`.
`name`	The application's name.

auth_device

Information about the device used to approve or deny authentication.

ip The IP address of the authentication device.

key The Duo identifier of the authentication device (the phone_id value for a phone, the webauthnkey value for a security key, etc.).

location

The GeoIP location of the authentication device, if available. The response may not include all location parameters.

`city`	The city name.
`country`	The country name. Refer to ISO 3166 for a list of possible countries.
`state`	The state, county, province, or prefecture.

name The name of the authentication device.

email The email address of the user, if known to Duo, otherwise none.

event_type The type of activity logged. one of: "authentication" or "enrollment".

factor

The authentication factor. One of: "phone_call", "passcode", "yubikey_passcode", "digipass_go_7_token", "hardware_token", "duo_mobile_passcode", "bypass_code", "sms_passcode", "sms_refresh", "duo_push", "u2f_token", "remembered_device", or "trusted_network'".

isotimestamp

ISO8601 timestamp of the event.

ood_software

If authentication was denied due to out-of-date software, shows the name of the software, i.e. "Chrome", "Flash", etc.

No value if authentication was successful or authentication denial was not due to out-of-date software.

reason

Provide the reason for the authentication attempt result.

If result is "SUCCESS" then one of: "allow_unenrolled_user", "allowed_by_policy", "allow_unenrolled_user_on_trusted_network", "bypass_user", "remembered_device", "trusted_location", "trusted_network", "user_approved", "valid_passcode".

If result is "FAILURE" then one of: "anonymous_ip", "anomalous_push", "could_not_determine_if_endpoint_was_trusted", "denied_by_policy", "denied_network", "deny_unenrolled_user", "endpoint_is_not_in_management_system", "endpoint_failed_google_verification", "endpoint_is_not_trusted", "factor_restricted", "invalid_management_certificate_collection_state", "invalid_device", "invalid_passcode", "invalid_referring_hostname_provided", "location_restricted", "locked_out", "no_activated_duo_mobile_account", "no_disk_encryption", "no_duo_certificate_present", "touchid_disabled", "no_referring_hostname_provided", "no_response", "no_screen_lock", "no_web_referer_match", "out_of_date", "platform_restricted", "rooted_device", "software_restricted", "user_cancelled", "user_disabled", "user_mistake", "user_not_in_permitted_group", "user_provided_invalid_certificate", or "version_restricted".

If result is "ERROR" then: "error".

If result is "FRAUD" then: "user_marked_fraud".

Note that enrollment events have no associated reason.

result The result of the authentication attempt. One of: "success", "denied", "failure", "error", or "fraud".

timestamp An integer indicating the Unix timestamp of the event.

txid The transaction ID of the event.

user

Information about the authenticating user.

`groups`	Duo group membership information for the user.
`key`	The user's `user_id`.
`name`	The user's `username`.

Example Response

200 OK
{
    "stat": "OK",
    "response": {
        "authlogs": [
            {
                "access_device": {
                    "browser": "Chrome",
                    "browser_version": "67.0.3396.99",
                    "flash_version": "uninstalled",
                    "hostname": null,
                    "ip": "169.232.89.219",
                    "is_encryption_enabled": true,
                    "is_firewall_enabled": true,
                    "is_password_set": true,
                    "java_version": "uninstalled",
                    "location": {
                        "city": "Ann Arbor",
                        "country": "United States",
                        "state": "Michigan"
                    },
                    "os": "Mac OS X",
                    "os_version": "10.14.1",
                    "security_agents": []
                },
                "adaptive_trust_assessments": {
                    "more_secure_auth": {
                        "features_version": "3.0",
                        "model_version": "2022.07.19.001",
                        "policy_enabled": false,
                        "reason": "Normal level of trust; no detection of known attack pattern",
                        "trust_level": "NORMAL"
                    },
                    "remember_me": {
                        "features_version": "3.0",
                        "model_version": "2022.07.19.001",
                        "policy_enabled": false,
                        "reason": "Known Access IP",
                        "trust_level": "NORMAL"
                    }
                },
                "alias": "",
                "application": {
                    "key": "DIY231J8BR23QK4UKBY8",
                    "name": "Microsoft Azure Active Directory"
                },
                "auth_device": {
                    "ip": "192.168.225.254",
                    "key": "DP5BJ05HI4WRBVI4Q7JF",
                    "location": {
                        "city": "Ann Arbor",
                        "country": "United States",
                        "state": "Michigan"
                    },
                    "name": "My iPhone X (734-555-2342)"
                },
                "email": "narroway@example.com",
                "event_type": "authentication",
                "factor": "duo_push",
                "isotimestamp": "2020-02-13T18:56:20.351346+00:00",
                "ood_software": null,
                "reason": "user_approved",
                "result": "success",
                "timestamp": 1581620180,
                "trusted_endpoint_status": "not trusted",
                "txid": "340a23e3-23f3-23c1-87dc-1491a23dfdbb",
                "user": {
                    "groups": [
                        "Duo Users",
                        "CorpHQ Users"
                    ],
                    "key": "DU3KC77WJ06Y5HIV7XKQ",
                    "name": "narroway@example.com"
                }
            },
         ],
        "metadata": {
            "next_offset": [
                "1532951895000",
                "af0ba235-0b33-23c8-bc23-a31aa0231de8"
            ],
            "total_objects": 1
        }
    },
}

Authentication Logs (Legacy v1)

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

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

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

We recommend requesting logs no more than once per minute.

GET /admin/v1/logs/authentication

Parameters

Parameter	Required?	Description
`mintime`	Optional	Only return records that have a Unix `timestamp` in seconds 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.

`browser`	The web browser used for access.
`browser_version`	The browser version.
`flash_version`	The Flash plugin version used, if present, otherwise "uninstalled".
`java_version`	The Java plugin version used, if present, otherwise "uninstalled".
`os`	The device operating system name.
`os_version`	The device operating system version.
`trusted_endpoint_status`	Shows whether the endpoint is a Duo managed endpoint. One of "trusted", "not trusted", "unknown", or "error". Returned for Duo Beyond customers only.

alias The username alias used to log in. No value if the user logged in with their username instead of a username alias.

device Device used to authenticate, if present, otherwise none.

email The email address of the user, if known to Duo, otherwise none.

factor

The authentication factor. One of: "Bypass Code", "Digipass GO 7 Token", "Duo Mobile Inline Auth", "Duo Mobile Passcode", "Duo Push", "Passcode", "Phone Call", "Hardware Token", "Remembered Device", "Security Key (WebAuthn)", "SMS Passcode", "SMS Refresh", "Touch ID (WebAuthn)", "Trusted Network", "U2F Token", or "Yubikey Passcode".

integration The integration name.

ip The IP address that this request originated from.

isotimestamp

ISO8601 timestamp of the event.

location

The GeoIP location from which the user authenticated, if available. The response may not include all location parameters.

`city`	The city name.
`state`	The state, county, province, or prefecture.
`country`	The country code. Refer to ISO 3166 for a list of possible countries.

new_enrollment true if the user enrolled a new device at the authentication prompt; false if authenticated with a previously enrolled device.

ood_software

If authentication was denied due to out-of-date software, shows the name of the software, i.e. "Chrome", "Flash", etc.

No value if authentication was successful or authentication denial was not due to out-of-date software.

reason

Provide the reason for the authentication attempt result.

If result is "SUCCESS" then one of: "Allow unenrolled user", "Allowed by policy", "Bypass user", "Remembered device", "Trusted location", "Trusted network", "User approved", "Valid passcode".

If result is "FAILURE" then one of: "Anonymous IP", "Anomalous push", "Call timed out", "Couldn't determine if endpoint was trusted", "Denied by policy", "Deny unenrolled user", "Endpoint is not in Management System", "Factor restricted", "Invalid device", "Invalid passcode", "Location restricted", "Locked out", "No Duo certificate present", "No response", "No disk encryption", "No fingerprint", "No screen lock", "Out of date", "Platform restricted", "Rooted device", "Software Restricted", "User cancelled", "User is disabled", "User mistake", "User provided an invalid certificate", or "Version restricted".

If result is "ERROR" then: "Error".

If result is "FRAUD" then: "User marked fraud".

Note that enrollment events have no associated reason.

result The result of the authentication attempt. One of: "success", "denied", "failure", "error", or "fraud".

timestamp An integer indicating the Unix timestamp of the event.

username The authenticating user's username.

Example Response

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

  }]
}

Activity Logs

This API endpoint is currently in Public Preview for Duo Access and Beyond. Interested MFA plan customers can contact us to join the preview.

Returns a paged list of activity log events ranging from the last 180 days up to as recently as two minutes before the API request. The events returned are subject to log retention, if set up in the account, as described here. To fetch all results, call repeatedly with the next_offset paging parameter as long as the result metadata has next_offset values. Requires "Grant read log" API permission.

There is an intentional two-minute delay in the availability of new activity events in the API response. Duo operates a large-scale distributed system, and this two-minute buffer period ensures that calls will return consistent results. Querying for results more recent than two minutes will return as empty.

We recommend requesting logs no more than once per minute.

GET /admin/v2/logs/activity

Parameters

Query Parameter Required? Allow Multiple? Description

mintime

Required

Return records that have a 13 character Unix timestamp in milliseconds of mintime or later. This value must be strictly less than maxtime.

Example: 1661022959934

maxtime

Required

Return records that have a 13 character Unix timestamp in milliseconds of maxtime or earlier. This value must be strictly greater than mintime.

Maximum: 180 days

Example: 1661022969934

limit

Optional

The maximum number of records returned.

Default: 100; Max: 1000

next_offset

Optional

Yes

When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset.

Default: None

Example: next_offset=1547486297000,5bea1c1e-612c-4f1d-b310-75fd31385b15

sort

Optional

The order in which to return records. One of:

Value	Description
`ts:asc`	Return logs in chronological order.
`ts:desc`	Return logs in reverse chronological order.

Default: ts:desc

Response Codes

Response	Meaning
200	Success.
400	Invalid or missing parameters or `mintime` is after the `maxtime`.

Response Format

Key Value

items

List of activity logs. Information included:

access_device

Information about the device used to perform the activity, to the extent that we can capture it. All fields are optional as non-external actors will not have any information to record here.

browser The web browser used for access.

browser_version The web browser version.

ip

IP information of the access device.

address IP address of access device.

location

The location details of the device, if available.

`city`	The city name.
`country`	The country code. Refer to ISO 3166 for a list of possible countries.
`state`	The state, county, province, or prefecture.

os The device operating system name.

os_version The device operating system version.

action

The action is a string representing the action the actor performed. If a target is present, the action was performed on that target. One of:

Action	Description
`admin_activate_duo_push`	An administrator or user activates a 2FA device for Duo Push.
`admin_rectivates_duo_push`	Administrator reactivates an admin or user 2FA device for Duo Push.
`hardtoken_create`	Created a hardware token.
`phone_create`	Added phone.
`phone_update`	Modified phone.
`u2ftoken_create`	Created U2F token.
`webauthncredential_create`	Created WebAuthn authenticator and associated it with the user.

activity_id Transaction ID of the event.

actor

The actor represents the entity performing the action.

details

If actor type is user, following fields would be populated:

created Timestamp when actor was created.

group

The group membership of the actor.

`key`	The group's integration key.
`name`	The group's name.

last_login Timestamp of last login.

status Status of actor. One of: Active, Bypass, Disabled, or Locked Out.

key Identifier of the actor.

name Name of the actor.

type Type of actor. One of: admin, user, adminapi, or system.

akey Unique identifier of entity associated with the activity log.

application

The integration used to perform the activity.

`key`	The application's integration key.
`name`	The application's name.
`type`	The application's type.

target

The target represents the entity on which the action was performed. The target is optional, as not all activity may represent a change to another entity.

`details`	Key-value pair of properties about the target. The properties for a given target may vary by target type, but should be consistent for the same type.
`key`	Key of the target that corresponds to the target type.
`name`	Name of the target.
`type`	The target type. One of: `hardtoken`, `phone`, `u2f_token`, `user`, `webauthn_credentials`, or `authproxy`.

ts The time at which the activity took place, to the best of our ability to record it. This may not always be the exact time the event took place, but should be extremely close.

Example Response

{
  "stat": "OK",
  "response": {
        "items": [
            {
                "access_device": {
                    "browser": "Chrome",
                    "browser_version": "111.0.0.0",
                    "ip": {
                        "address": "172.34.40.116"
                    },
                    "location": {
                        "city": "Ann Arbor",
                        "country": "United States",
                        "state": "Michigan"
                    },
                    "os": "Mac OS X",
                    "os_version": "10.15.7"
                },
                "action": "webauthncredential_create",
                "activity_id": "720b8360-078b-47c4-adc7-7968df1caef0",
                "actor": {
                    "details": "{\"created\": \"2015-09-25T23:17:40.000000+00:00\", \"last_login\": 
                    \"2023-03-21T19:51:09.000000+00:00\", \"status\": \"Active\", \"groups\": [{\"name\": 
                    \"CorpHQ_Users\", \"key\": \"DGAZ172QBWDM26AK8ITK\"}, {\"name\": \"ITAdmins\", \"key\": 
                    \"DGK3B7XTSIP00LKHK1RD\"}, {\"name\": \"yee\", \"key\": \"DGKZWSBCDADEVFGFK5NR\"}]}",
                    "key": "DU64TKJPJ0SHFWKO2LNBC",
                    "name": "sogilby",
                    "type": "user"
                },
                "akey": "DAAR5FO0OZ4VYZA0WOB2",
                "application": {
                    "key": "DILSVDEYH66TBHKIXGR9",
                    "name": "Acme Corp",
                    "type": "websdk"
                },
                "old_target": null,
                "target": {
                    "details": "{\"authenticator_type\": \"Security key\", \"transport_types\": \"usb\", 
                    \"passwordless_authorized\": false, \"browser\": \"Chrome\", \"browser_version\": 
                    \"111.0.0.0\", \"os\": \"Mac OS X\", \"os_version\": \"10.15.7\", \"user_agent\": 
                    \"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) 
                    Chrome/111.0.0.0 Safari/537.36\", \"credential_name\": \"Security key\"}",
                    "key": "WAUKH0IMTGP00L90LT4KM",
                    "name": "WAUKH0IMTG3EDD4DT4KM",
                    "type": "webauthn_credential"
                },
                "ts": "2023-03-21T15:51:22.591015+00:00"
            }
        ],
        "metadata": {
            "next_offset": "1666714065304,5bf1a860-fe39-49e3-be29-217659663a74",
            "total_objects": 1
        }
    }
}

Administrator Logs

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

We recommend requesting logs no more than once per minute.

GET /admin/v1/logs/administrator

Parameters

Parameter	Required?	Description
`mintime`	Optional	Only return records that have a Unix `timestamp` in seconds after `mintime`. This can help to avoid fetching records that have already been retrieved.

Response Codes

Response	Meaning
200	Success.

Response Format

Key Value

action

The type of change that was performed. Possible values:

Type	Description
"accepted_dtm_opt_in"	Admin accepted Duo Trust Monitor terms
"activation_begin"	New admin begins setup using activation link
"activation_complete"	New admin completes account setup
"activation_create_link"	New admin activation link created
"activation_delete_link"	Admin activation link deleted
"activation_send_email"	Emailed activation link to admin
"activation_set_password"	New admin sets login password during initial setup
"accountsapi_request_ip_denied"	Accounts API request blocked due to IP restriction
"ad_connection_config_download"	Admin downloaded authproxy.cfg file for an Active Directory sync connection
"ad_sync_begin"	Active Directory Sync started
"ad_sync_by_user_begin"	Active Directory Sync of individual user started
"ad_sync_by_user_finish"	Active Directory Sync of individual user completed
"ad_sync_config_download"	Active Directory Sync configuration download
"ad_sync_failed"	Active Directory Sync failed
"ad_sync_finish"	Active Directory Sync completed
"admin_2fa_error"	Administrator issue completing secondary authentication
"admin_account_switch"	Administrator switched to this account from another Duo account
"admin_activation_create"	An admin activation link was created
"admin_activation_delete"	An admin activation link was deleted
"admin_activate_duo_push"	Administrator activates an admin's 2FA device for Duo Push
"admin_create"	Added administrator
"admin_delete"	Deleted administrator
"admin_factor_restrictions_update"	Modified admin factor restrictions
"admin_login"	Administrator logged in
"admin_login_error"	Administrator issue completing primary password or SAML authentication
"admin_lockout"	Administrator locked out after too many failed login attempts
"admin_reactivates_duo_push"	Administrator reactivates an admin's 2FA device for Duo Push
"admin_reset_password"	Administrator changed password via emailed reset link
"admin_send_reset_password_email"	Password reset email sent to administrator
"admin_single_sign_on_cert_create"	Generated a new certificate for admin SSO
"admin_single_sign_on_cert_update"	Modified admin SSO configuration
"admin_update"	Modified administrator
"adminapi_request_ip_denied"	Admin API request blocked due to IP restriction
"azure_dir_connection_authorize"	Authorized Azure Active Directory connection
"azure_directory_create"	Azure Active Directory sync created
"azure_directory_delete"	Azure Active Directory deleted
"azure_directory_update"	Azure Active Directory sync modified
"azure_sync_begin"	Full Azure Active Directory Sync started
"azure_sync_by_user_begin"	Azure Active Directory Sync of individual user started
"azure_sync_by_user_finish"	Azure Active Directory Sync of individual user completed
"azure_sync_finish"	Full Azure Active Directory Sync completed
"azure_sync_fail"	Azure Active Directory Sync failed
"bypass_create"	Bypass code created for a user
"bypass_delete"	Bypass code deleted
"bypass_view"	Viewed a user's bypass code
"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 for sync
"directory_delete"	Deleted directory
"directory_groups_update"	Modified directory sync groups
"directory_sync_pause"	Scheduled directory sync paused by administrator or due to expired Azure Active Directory authorization
"directory_sync_resume"	Scheduled directory sync resumed by administrator or after Azure Active Directory reauthorization
"directory_update"	Modified directory sync
"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_bulk_view"	Viewed application's secret key or client ID via Admin API
"integration_skey_view"	Viewed application's secret key or client ID in the Admin Panel
"integration_update"	Modified application
"ldap_connection_skey_view"	View secret key for Active Directory or OpenLDAP sync connection
"ldap_connection_skey_reset"	Reset secret key for Active Directory or OpenLDAP sync connection
"openldap_connection_config_download"	Admin downloaded authproxy.cfg file for an OpenLDAP sync connection
"openldap_sync_begin"	OpenLDAP Sync started
"openldap_sync_by_user_begin"	OpenLDAP Sync of individual user started
"openldap_sync_by_user_finish"	OpenLDAP Sync of individual user completed
"openldap_sync_config_download"	OpenLDAP Sync configuration download
"openldap_sync_failed"	OpenLDAP Sync failed
"openldap_sync_finish"	OpenLDAP Sync completed
"phone_associate"	Associated phone with user
"phone_create"	Added phone
"phone_delete"	Deleted phone
"phone_disassociate"	Disassociated phone from user
"phone_update"	Modified phone
"policy_create"	Added a custom policy
"policy_delete"	Deleted a custom policy
"policy_update"	Modified a policy
"pwl_initial_activation"	Admin accepted Duo Passwordless terms
"regen_mobile"	Generated a new Duo Mobile Activation Code
"regen_sms"	Generated new SMS passcodes and sent them to a phone
"resend_enroll_codes"	Resend all enroll codes
"send_enroll_code"	Send an enroll code
"u2ftoken_create"	Created U2F token
"u2ftoken_delete"	Deleted U2F token
"updated_risk_profile"	Admin modified Trust Monitor risk profile
"user_bulk_activate"	Bulk mobile activation sent
"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
"webauthncredential_create"	Created a WebAuthn credential
"webauthncredential_delete"	Deleted a WebAuthn credential

description

String detailing what changed, either as free-form text or serialized JSON.

When the description contains JSON it may be either a serialized object or a serialized array of objects. Each key in the object(s) corresponds to a property that was changed. This JSON is intended only to summarize the change, not to be de-serialized.

The first example below is for a "user_update" action. The object that changed was a user whose Duo username is "jsmith". The change saved new values for the user's "notes" and "realname" fields, overwriting the previous values if any were set. They correspond to the similarly named fields in the Modify User call in the Admin API and the User Details page in the Duo Admin Panel.

The second example shows an "admin_login_error" action. The administrator's login attempt failed because the admin attempted to use SSO but, as indicated by the "error" in the description, SAML login is disabled for administrators on that account.

isotimestamp

ISO8601 timestamp of the event.

object The object that was acted on. For example: "jsmith" (for users), "(555) 713-6275 x456" (for phones), or "HOTP 8-digit 123456" (for tokens).

timestamp An integer indicating the Unix timestamp of the event.

username The full name of the administrator who performed the action in the Duo Admin Panel. If the action was performed with the API this will be "API". Automatic actions like deletion of inactive users have "System" for the username. Changes synchronized from Directory Sync will have a username of the form (example) "AD Sync: name of directory."

Example Responses

{
  "stat": "OK",
  "response": [{
      "action": "user_update",
      "description": "{\"notes\": \"Joe asked for their nickname to be displayed instead of Joseph.\", \"realname\": \"Joe Smith\"}",
      "isotimestamp": "2020-01-24T15:09:42+00:00",
      "object": "jsmith",
      "timestamp": 1579878582,
      "username": "admin"
  }]
}

{
  "stat": "OK",
  "response": [{
      "action": "admin_login_error",
      "description": "{\"ip_address\": \"10.1.23.116\", \"error\": \"SAML login is disabled\", \"email\": \"narroway@example.com\"}",
      "isotimestamp": "2020-01-23T16:18:58+00:00",
      "object": null,
      "timestamp": 1579796338,
      "username": ""
  }]
}

Telephony Logs

This API endpoint is currently in Public Preview.

Returns a paged list of telephony log events ranging from the last 180 days up to as recently as two minutes before the API request. The events returned are subject to log retention, if set up in the account, as described here. To fetch all results, call repeatedly with the next_offset paging parameter as long as the result metadata has next_offset values. Requires "Grant read log" API permission.

There is an intentional two-minute delay in the availability of new telephony events in the API response. Duo operates a large-scale distributed system, and this two-minute buffer period ensures that calls will return consistent results. Querying for results more recent than two minutes will return as empty.

The v2 handler provides new querying capabilities and contextual information for events unavailable in the legacy v1 handler.

We recommend requesting logs no more than once per minute.

GET /admin/v2/logs/telephony

Parameters

Query Parameter Required? Allow Multiple? Description

mintime

Required

Return records that have a 13 character Unix timestamp in milliseconds of mintime or later. This value must be strictly less than maxtime.

Example: 1661022959934

maxtime

Required

Return records that have a 13 character Unix timestamp in milliseconds of maxtime or earlier. This value must be strictly greater than mintime.

Maximum: 180 days

Example: 1661022969934

limit

Optional

The maximum number of records returned.

Default: 100; Max: 1000

next_offset

Optional

Yes

When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset.

Default: None

Example: next_offset=1547486297000,5bea1c1e-612c-4f1d-b310-75fd31385b15

sort

Optional

The order in which to return records. One of:

Value	Description
`ts:asc`	Return logs in chronological order.
`ts:desc`	Return logs in reverse chronological order.

Default: ts:desc

Response Codes

Response	Meaning
200	Success.
400	Invalid or missing parameters or `mintime` is after the `maxtime`.

Response Format

Key Value

items

List of telephony logs. Information included:

`context`	The context under which this telephony event was used (e.g. Administrator Login).
`credits`	How many telephony credits this event used.
`phone`	The phone number that initiated this event.
`telephony_id`	A unique identifier for the telephony event.
`ts`	The time at which the telephony event was first recorded, to the best of our ability to record it. This may not always be the exact time the event took place, but should be extremely close.
`txid`	A unique identifier that relates to the successful authentication attempt using this telephony event.
`type`	The event type. Either "sms" or "phone".

Example Response

{
  "stat": "OK",
  "response": {
        "items": [
            {
                "context": "enrollment",
                "credits": 1,
                "phone": "+12125556707",
                "telephony_id": "220f89ff-bff8-4466-b6cb-b7787940ce68",
                "ts": "2023-03-21T22:34:49.466370+00:00",
                "txid": "2f5d34d3-053f-422c-9dd4-77a5d58706b1",
                "type": "sms"
            },
            {
                "context": "authentication",
                "credits": 2,
                "phone": "+17345551311",
                "telephony_id": "60799fee-f08f-4ba8-971f-4e53b3473e9a",
                "ts": "2023-01-26T20:54:12.573580+00:00",
                "txid": "373bd5f3-1e42-4a5d-aefa-b33ae278fac8",
                "type": "phone"
            },
            {
                "context": "administrator login",
                "credits": 0,
                "phone": "+13135559542",
                "telephony_id": "5bf1a860-fe39-49e3-be29-217659663a74",
                "ts": "2022-10-25T16:07:45.304526+00:00",
                "txid": "fb0c129b-f994-4d3d-953b-c3e764272eb7",
                "type": "sms"
            }
        ],
        "metadata": {
            "next_offset": "1666714065304,5bf1a860-fe39-49e3-be29-217659663a74",
            "total_objects": 3
        }
    }
}

Telephony Logs (Legacy v1)

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

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

We recommend requesting logs no more than once per minute.

GET /admin/v1/logs/telephony

Parameters

Parameter	Required?	Description
`mintime`	Optional	Only return records that have a Unix `timestamp` in seconds after `mintime`. This can help to avoid fetching records that have already been retrieved.

Response Codes

Response	Meaning
200	Success.

Response Format

Key	Value
`context`	How this telephony event was initiated. One of: "administrator login", "authentication", "enrollment", or "verify".
`credits`	How many telephony credits this event cost.
`isotimestamp`	ISO8601 timestamp of the event.
`phone`	The phone number that initiated this event.
`timestamp`	An integer indicating the Unix timestamp of the event.
`type`	The event type. Either "sms" or "phone".

Example Response

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

Offline Enrollment Logs

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

We recommend requesting logs no more than once per minute.

GET /admin/v1/logs/offline_enrollment

Parameters

Parameter	Required?	Description
`mintime`	Optional	Only return records that have a Unix `timestamp` in seconds of `mintime` or later. Use `mintime+1` to avoid receiving duplicate data.

Response Codes

Response	Meaning
200	Success.

Response Format

Key Value

action The offline enrollment operation. One of "o2fa_user_provisioned", "o2fa_user_deprovisioned", or "o2fa_user_reenrolled".

description

Information about the Duo Windows Logon client system as reported by the application.

`user_agent`	The Duo Windows Logon application version information and the Windows OS version and platform information.
`hostname`	The host name of the system where Duo Windows Logon is installed.
`factor`	The type of authenticator used for offline access. One of "duo_otp" or "security_key".

isotimestamp

ISO8601 timestamp of the event.

object The Duo Windows Logon integration's name.

timestamp An integer indicating the Unix timestamp of the event.

username The Duo username.

Example Response

{
  "stat": "OK",
  "response": [{
      "action": "o2fa_user_provisioned",
      "description": "{\"user_agent\": \"DuoCredProv/4.0.6.413 (Windows NT 6.3.9600; x64; Server)\", \"hostname\": \"WKSW10x64\", \"factor\": \"duo_otp\"}",
      "isotimestamp": "2019-08-30T16:10:05+00:00",
      "object": "Acme Laptop Windows Logon",
      "timestamp": 1567181405,
      "username": "narroway"
  }]
}

Trust Monitor

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

Retrieve Events

Returns a paged list of events surfaced by Trust Monitor from the last 180 days. To fetch all results, call repeatedly with the next_offset paging parameter as long as the result metadata has next_offset values. Requires "Grant read log" API permission.

We recommend requesting Trust Monitor events no more than once per minute.

GET /admin/v1/trust_monitor/events

Parameters

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

Paging Parameter Required? Description

limit

Optional

The maximum number of records returned.

Default: 100; Max: 500

offset

Optional

The offset from 0 at which to start record retrieval.

When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset.

Default: 0

Parameter Required? Description

mintime

Required

Return records that have a 13 character Unix timestamp in milliseconds of mintime or later. This value must be strictly less than maxtime.

maxtime

Required

Return records that have a 13 character Unix timestamp in milliseconds of maxtime or earlier. This value must be strictly greater than mintime.

type

Optional

The type of security event.

Type	Description
`auth`	Return security events that are denied anomalous authentications.
`bypass_status_enabled`	Return security events that are bypass status enabled.
`device_registration`	Return security events that are device registrations.

Response Codes

Response	Meaning
200	Success. Returns a list of security events.
400	Invalid or missing parameters.

Response Format

Key Value

events

Array of events that match the Parameters. The information returned for each event includes:

bypass_status_enabled

An integer indicating the Unix timestamp in milliseconds when bypass status was enabled for the user or group.

Returned for events with type=bypass_status.

enabled_by

The application or the administrator that enabled bypass status.

Returned for events with type=bypass_status.

enabled_for

The user or group with bypass status.

Returned for events with type=bypass_status.

explanations

An array of objects describing why Trust Monitor surfaced the event. The summary provides additional details.

Events with type=auth:

The type value will be one of: GRANTED_AUTH, NEW_COUNTRY_CODE, NEW_DEVICE, NEW_FACTOR, NEW_NETBLOCK, UNREALISTIC_GEOVELOCITY, UNUSUAL_COUNTRY_CODE, UNUSUAL_DEVICE, UNUSUAL_FACTOR, UNUSUAL_NETBLOCK, UNUSUAL_TIME_OF_DAY, or USER_MARKED_FRAUD.

Events with type=device_registration:

The type value will be one of: REGISTER_INACTIVE_USER, REGISTER_OS_OUTDATED, REGISTER_UNLOCK, or REGISTER_TAMPERED.

from_common_netblock

A boolean describing if this event was created from a common IP netblock. Either true or false.

Returned for events with type=auth.

from_new_user

A boolean describing if this event was created for a new user. Either true or false.

Returned for events with type=auth or type=device_registration.

low_risk_ip

A boolean describing if this event was created from an IP address identified in the Risk Profile configuration as a low risk IP address. Either true or false.

Returned for events with type=auth.

priority_event

A boolean describing if the event matches the Risk Profile configuration. Either true or false.

priority_reasons

An array of objects describing how the event matches the Trust Monitor Risk Profile configuration. Each object contains:

`type`	The type of priority reason for the event's match.
`label`	The label of the priority reason for the event's match.

Returned for events with type=auth or type=device_registration.

sekey

The unique identifier for this event as a 20 character string. This is unique across all different event types.

state

A string describing the state of the event. One of statenew or stateprocessed.

state_updated_timestamp

An integer indicating the Unix timestamp in milliseconds of the last change to the state of the event.

surfaced_auth

An object which represents the actual authentication. See the Authentication Logs response format for authentication event details.

Returned for events with type=auth.

surfaced_timestamp

An integer indicating the Unix timestamp in milliseconds when the event was surfaced by Trust Monitor.

triaged_as_interesting

A boolean describing if this event was triaged as being interesting or not interesting. Either true or false.

triage_event_uri

A string representing the URI of the security event, which a Duo administrator can use to view and process the surfaced event in the Duo Admin Panel.

Returned for events with type=auth.

type

The type of event, as a string. One of auth, bypass_status, or device_registration.

Example Response

Authentication Event:

{
    "stat": "OK",
    "response": {
        "events": [
                        {
                "explanations": [
                    {
                        "summary": "amanda_tucker has not logged in from this location recently.",
                        "type": "NEW_COUNTRY_CODE"
                    },
                    {
                        "summary": "amanda_tucker has not logged in from this IP recently.",
                        "type": "NEW_NETBLOCK"
                    },
                    {
                        "summary": "amanda_tucker has not accessed this application recently.",
                        "type": "NEW_IKEY"
                    }
                ],
                "from_common_netblock": true,
                "from_new_user": false,
                "low_risk_ip": false,
                "priority_event": true,
                "priority_reasons": [
                    {
                        "label": "CN",
                        "type": "country"
                    }
                ],
                "sekey": "SEDOR9BP00L23C6YUH5",
                "state": "new",
                "state_updated_timestamp": null,
                "surfaced_auth": {
                    "access_device": {
                        "browser": "Chrome",
                        "browser_version": "86.0.4240.198",
                        "epkey": "EP18JX1A10AB102M2T2X",
                        "flash_version": null,
                        "hostname": null,
                        "ip": "17.88.232.83",
                        "is_encryption_enabled": "unknown",
                        "is_firewall_enabled": "unknown",
                        "is_password_set": "unknown",
                        "java_version": null,
                        "location": {
                            "city": "Shanghai",
                            "country": "China",
                            "state": "Shanghai"
                        },
                        "os": "Windows",
                        "os_version": "10",
                        "security_agents": "unknown"
                    },
                    "alias": "unknown",
                    "application": {
                        "key": "DIUD2X62LHMPDP00LXS3",
                        "name": "Microsoft Azure Active Directory"
                    },
                    "auth_device": {
                        "ip": null,
                        "key": null,
                        "location": {
                            "city": null,
                            "country": null,
                            "state": null
                        },
                        "name": null
                    },
                    "email": "",
                    "event_type": null,
                    "factor": "not_available",
                    "isotimestamp": "2020-11-17T03:19:13.092+00:00",
                    "ood_software": "",
                    "reason": "location_restricted",
                    "result": "denied",
                    "timestamp": 1605583153,
                    "trusted_endpoint_status": null,
                    "txid": "436694ad-467c-4aed-b048-8ad--f58e04c",
                    "user": {
                        "groups": [
                            "crazy"
                        ],
                        "key": "DUN73JE5M92DP00L4ZYS",
                        "name": "amanda_tucker"
                    }
                },
                "surfaced_timestamp": 1605602911680,
                "triage_event_uri": "https://admin-xxxxxxxx.duosecurity.com/trust-monitor?sekey=SEDOR9BP00L23C6YUH5",
                "triaged_as_interesting": false,
                "type": "auth"
            }
        ],
        "metadata": {
            "next_offset": "31229"
        }
    },
}

Bypass Status Enabled Event:

{
    "stat": "OK",
    "response": {
        "events": [
                        {
                "bypass_status_enabled": 1604337058989,
                "enabled_by": {
                    "key": "DEWGH6P00LT2R0I60UI",
                    "name": "Ellery Munson"
                },
                "enabled_for": {
                    "key": "DUN73JE5M92DP00L4ZYS",
                    "name": "amanda_tucker"
                },
                "priority_event": true,
                "priority_reasons": [],
                "sekey": "SEDOR9BP00L23C6YUH5",
                "state": "new",
                "state_updated_timestamp": null,
                "surfaced_timestamp": 1605602911680,
                "triaged_as_interesting": false,
                "type": "bypass_status"
            }
        ],
        "metadata": {}
    },
}

Device Registration Event:

{
    "stat": "OK",
    "response": {
        "events": [
                        {
                "explanations": [
                    {
                        "summary": "The registered device has an out-of-date version of the operating system installed.",
                        "type": "REGISTER_OS_OUTDATED"
                    }
                ],
                "from_new_user": false,
                "priority_event": false,
                "priority_reasons": [],
                "sekey": "SEDOR9BP00L23C6YUH7",
                "state": "new",
                "state_updated_timestamp": null,
                "surfaced_timestamp": 1675893605269,
                "triaged_as_interesting": false,
                "type": "device_registration"
            }
        ],
        "metadata": {}
    },
}

Settings

Retrieve Settings

Returns global Duo settings. These settings can also be viewed and set in the Duo Admin Panel. Requires "Grant settings" API permission.

GET /admin/v1/settings

Parameters

This API endpoint has no parameters.

Response Codes

Response	Meaning
200	Success. Returns settings.

Response Format

Key	Value
`caller_id`	Automated calls will appear to come from this number. This does not apply to text messages.
`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.
`helpdesk_bypass`	Grants permission for administrators with the Help Desk role to generate bypass codes for users. One of `allow` (default value), `limit`, or `deny`.
`helpdesk_bypass_expiration`	Integer specifying a default expiration for bypass codes generated by Help Desk admins, in minutes. If not set, Help Desk admins may change bypass code expiration from the default 60 minutes after creation if `helpdesk_bypass` is set to `allow`.
`helpdesk_can_send_enroll_email`	Permits Help Desk administrators to send or resend enrollment emails to users. One of `true` or `false` (default).
`helpdesk_message`	Legacy parameter; no effect if specified. Use the Retrieve Custom Messaging endpoint.
`inactive_user_expiration`	Users will be automatically deleted if they are inactive (no successful logins) for a this amount of days.
`keypress_confirm`	The key for users to press to authenticate, or empty if any key should be pressed to authenticate.
`keypress_fraud`	The key for users to press to report fraud, or empty if any key should be pressed to authenticate.
`language`	The language used in the traditional Duo browser-based user authentication prompt. One of: "EN", "DE", "FR". Default: "EN"
`lockout_expire_duration`	If non-zero, an integer indicating the time in minutes until a locked-out user's status reverts to "Active". If `null` or `0`, a user remains locked out until their status is manually changed (By an admin or API call). Minimum: `5` minutes. Maximum: `30000` minutes.
`lockout_threshold`	The number of consecutive failed authentication attempts before the user's status is set to "Locked Out" and the user is denied access.
`log_retention_days`	When set, log entries older than the specified number of days are purged. Logs retained indefinitely if `null`. Note that the log retention setting does not change the 180 day limitation for viewing and retrieving log information in the Duo Admin Panel, exported reports, or via this API. Minimum: `1` day. Maximum: `365` days.
`minimum_password_length`	An integer indicating the minimum number of characters that an administrator's Duo Admin Panel password must contain. This is only enforced on password creation and reset; existing passwords will not be invalidated. Default: `12`.
`mobile_otp_enabled`	Legacy parameter; no effect if specified and always returns `false`. Use Duo Authentication Method policies to configure this setting.
`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`	Legacy parameter; no effect if specified and always returns `false`. Use Duo Authentication Method policies to configure this setting.
`sms_batch`	An integer that indicates how many passcodes to send at one time, up to 10.
`sms_enabled`	Legacy parameter; no effect if specified and always returns `false`. Use Duo Authentication Method policies to configure this setting.
`sms_expiration`	The time in minutes to expire and invalidate SMS passcodes, up to 16,777,215.
`sms_message`	Description sent with every batch of SMS passcodes.
`sms_refresh`	If `1`, a new set of SMS passcodes will automatically be sent after the last one is used. If `0`, a new set will not be sent.
`telephony_warning_min`	An integer indicating the number of telephony credits at which an alert will be sent for low credits.
`timezone`	This is the timezone used when displaying timestamps in the Duo Admin Panel.
`user_managers_can_put_users_in_bypass`	Permits User Manager administrators to apply "Bypass" status to users. One of `true` (default) or `false`.
`user_telephony_cost_max`	An integer indicating the maximum number of telephony credits a user may consume in a single authentication event. This excludes Duo administrators authenticating to the Duo administration panel. Default: `20`.
`voice_enabled`	Legacy parameter; no effect if specified and always returns `false`. Use Duo Authentication Method policies to configure this setting.

Example Response

{
  "stat": "OK",
  "response": {
      "caller_id": "+15035551000",
      "fraud_email": "example@example.com",
      "fraud_email_enabled": true,
      "helpdesk_bypass": "allow",
      "helpdesk_bypass_expiration": 0,
      "helpdesk_can_send_enroll_email": false,
      "helpdesk_message": "",
      "inactive_user_expiration": 30,
      "keypress_confirm": "#",
      "keypress_fraud": "*",
      "language": "EN",
      "lockout_expire_duration": null,
      "lockout_threshold": 10,
      "log_retention_days": null,
      "minimum_password_length": 12,
      "mobile_otp_enabled": false,
      "name": "Acme Corp",
      "password_requires_lower_alpha": true,
      "password_requires_numeric": true,
      "password_requires_special": false,
      "password_requires_upper_alpha": true,
      "push_enabled": false,
      "req_fips_passcodes_android": false,
      "security_checkup_enabled": 1,
      "sms_batch": 1,
      "sms_enabled": false,
      "sms_expiration": 10,
      "sms_message": "SMS passcodes",
      "sms_refresh": 0,
      "telephony_warning_min": 0,
      "timezone": "UTC",
      "user_managers_can_put_users_in_bypass": true,
      "user_telephony_cost_max": 20.0,
      "voice_enabled": false,
  }
}

Modify Settings

Change global Duo settings. Requires "Grant settings" API permission.

POST /admin/v1/settings

Parameters

Parameter	Required?	Description
`caller_id`	Optional	Automated calls will appear to come from this number. This does not apply to text messages. Customizing this number may cause telephony providers to flag your number as fraudulent and result in failed user authentications.
`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.
`helpdesk_bypass`	Optional	Grants permission for administrators with the Help Desk role to generate bypass codes for users. The default value `allow` permits unrestricted generation of bypass codes, `limit` plus a value for `helpdesk_bypass_expiration` allows Help Desk admins to generate bypass codes with a preset expirtation, and `deny` prevents Help Desk admins from generating any bypass codes.
`helpdesk_bypass_expiration`	Optional	Integer specifying a default expiration for bypass codes generated by Help Desk admins, in minutes. If not set, Help Desk admins may change bypass code expiration from the default 60 minutes after creation if `helpdesk_bypass` is set to `allow`. If specifying a value, also set `helpdesk_bypass` to `limit`.
`helpdesk_can_send_enroll_email`	Optional	Permits Help Desk administrators to send or resend enrollment emails to users. Set to `true` to allow sending of enrollment emails. Default value is `false`.
`helpdesk_message`	Optional	Legacy parameter; no effect if specified. Use the Modify Custom Messaging endpoint.
`inactive_user_expiration`	Optional	Users will be automatically deleted if they are inactive (no successful logins) for this number of days. Minimum: `30` Maximum: `365`
`keypress_confirm`	Optional	The key for users to press to authenticate, or empty if any key should be pressed to authenticate. If this is empty, `keypress_fraud` must be as well.
`keypress_fraud`	Optional	The key for users to report fraud, or empty if any key should be pressed to authenticate. If this is empty, `keypress_confirm` must be as well.
`language`	Optional	Sets the language used in the browser-based user authentication prompt. One of: "EN", "DE", "FR". Default: "EN"
`lockout_expire_duration`	Optional	If non-zero, the time in minutes until a locked-out user's status reverts to "Active". If `0`, a user remains locked out until their status is manually changed (By an admin or API call). Minimum: `5` Maximum: `30000`
`lockout_threshold`	Optional	The number of consecutive failed authentication attempts before the user's status is set to "Locked Out" and the user is denied access. Default is `10` attempts. Minimum: `1` Maximum: `9999`
`log_retention_days`	Optional	When set, log entries older than the specified number of days are purged. Logs retained indefinitely if `null`. Note that the log retention setting does not change the 180 day limitation for viewing and retrieving log information in the Duo Admin Panel, exported reports, or via this API. Default: `null` (no retention limit). Minimum: `1` day. Maximum: `365` days.
`minimum_password_length`	Optional	The minimum number of characters that an administrator's Duo Admin Panel password must contain. This is only enforced on password creation and reset; existing passwords will not be invalidated. Default: `12`. Minimum: `12` Maximum: `100`
`mobile_otp_enabled`	Optional	Legacy parameter; no effect if specified and always returns `false`. Use Duo Authentication Method policies to configure this setting.
`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	Legacy parameter; no effect if specified and always returns `false`. Use Duo Authentication Method policies to configure this setting.
`sms_batch`	Optional	The number of passcodes to send at one time, up to 10.
`sms_enabled`	Optional	Legacy parameter; no effect if specified and always returns `false`. Use Duo Authentication Method policies to configure this setting.
`sms_expiration`	Optional	The time in minutes to expire and invalidate SMS passcodes, or empty if they should not expire.
`sms_message`	Optional	Description sent with every batch of SMS passcodes.
`sms_refresh`	Optional	If `1`, a new set of SMS passcodes will automatically be sent after the last one is used. If `0`, a new set will not be sent.
`telephony_warning_min`	Optional	Configure a alert to be sent when the account has fewer than this many telephony credits remaining.
`timezone`	Optional	This is the timezone used when displaying timestamps in the Duo Admin Panel. Timezones must be entries in the IANA Time Zone Database, for example, "US/Eastern", "Australia/Darwin", "GMT".
`u2f_enabled`	Optional	Legacy parameter; no effect if specified. Use Duo Authentication Method policies to configure this setting.
`user_managers_can_put_users_in_bypass`	Optional	Permits User Manager administrators to apply "Bypass" status to users. Set to `false` to prevent User Managers from applying "Bypass" status. Default value is `true`.
`user_telephony_cost_max`	Optional	The maximum number of telephony credits a user may consume in a single authentication event. This excludes Duo administrators authenticating to the Duo administration panel. If you know the countries from which your users expect to authenticate with phone callback we recommend adjusting this down from the default to match the most expensive expected country to help avoid misuse, using the values from the Telephony Credits documentation. Default: `20`.
`voice_enabled`	Optional	Legacy parameter; no effect if specified and always returns `false`. Use Duo Authentication Method policies to configure this setting.

Response Codes

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

Response Format

Same as Retrieve Settings.

Example Response

Same as Retrieve Settings.

Retrieve Logo

Returns the custom logo displayed in the Duo authentication prompt and Duo Mobile. Requires "Grant settings API permission.

This logo customization is superseded by Custom Branding for Duo Beyond, Access, and MFA plan customers. Migrate to the new custom branding endpoint for increased functionality. This endpoint is deprecated and will stop working in a future update.

GET /admin/v1/logo

Parameters

This API endpoint has no parameters.

Response Codes

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

Response Format

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

Modify Logo

Returns the custom logo displayed in the Duo authentication prompt and Duo Mobile. This logo is sent to devices when they enroll with the mobile app. Currently enrolled devices must be re-activated to receive the new logo. Requires "Grant settings" API permission.

POST /admin/v1/logo

Parameters

Parameter	Required?	Description
`logo`	Required	Base-64 encoded PNG image data. The logo image must be in PNG format and not exceed 500 by 500 pixels and 200 KB. We recommend a 304 by 304 pixel logo image with a transparent background for the best results.

Response Codes

Response	Meaning
200	Success.
400	Invalid or missing parameters or PNG data.
600	Incorrect PNG base64 encoding.

Response Format

Empty string.

Delete Logo

Remove the logo from the Duo authentication prompt and future activation of Duo Mobile. Currently enrolled devices must be re-activated to remove the logo. Requires "Grant settings" API permission.

DELETE /admin/v1/logo

Parameters

This API endpoint has no parameters.

Response Codes

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

Response Format

Empty string.

Custom Branding

Custom branding is available to Duo Beyond, Duo Access, and Duo MFA plan customers.

Retrieve Live Custom Branding

Returns effective custom branding settings. These settings can also be viewed and set in the Duo Admin Panel. Requires "Grant settings" API permission.

GET /admin/v1/branding

Parameters

This API endpoint has no parameters.

Response Codes

Response	Meaning
200	Success. Returns live branding.

Response Format

Key	Value
`background_img`	A base64 encoded background image in PNG format. Shown in Duo SSO and Duo Universal Prompt.
`card_accent_color`	A CSS hex color shown as the hash symbol (#) followed by three or six hexadecimal digits, which represents the colored line appearing at the top of the interactive user interface. Shown in Duo SSO and Universal Prompt.
`logo`	A base64 encoded logo image in PNG format. Shown in Duo SSO, Duo Universal Prompt, and traditional prompt.
`page_background_color`	A CSS hex color shown as the hash symbol (#) followed by three or six hexadecimal digits, which represents the color appearing below the user interface and beneath any transparent background image. Shown in Duo SSO and Universal Prompt.
`powered_by_duo`	If `true`, Duo SSO, Duo Universal Prompt, and traditional prompt show the "Secured by Duo" branding. Otherwise, `false`.

Example Response

{
  "stat": "OK",
  "response": {
    "background_image": "iVBORw0KGgoAAAANSUhEUgAABQAAAAMgCAYAAAB8mM/7AAABrmlUWHRYTUw6Y29tLmFkb2JlLnhtcAAAAAAAPD94cGFja2V0IGJlZ2luPSLvu78iIGlkPSJXNU0wTXBDZWhpSHpyZVN6TlRjemtjOWQiPz4KPHg6eG1wbWV0YSB4bWxuczp4PSJhZG9iZTpuczptZXRhLyIgeDp4bXB0az0iQWRvYmUgWE1QIENvcmUgNi4wLWMwMDYgNzkuMTY0NzUzLCAyMDIxLzAyLzE1LTExOjUyOjEzICAgICAgICAiPgogPHJkZjpSREYggg==",
    "card_accent_color": "#144A94",
    "logo": "iVBORw0KGgoAAAANSUhEUgAAARQAAAEwCAYAAAB2TY5ZAAAACXBIWXMAAAwHAAAMBwF2myPLAAA55mlUWHRYTUw6Y29tLmFkb2JlLnhtcAAAAAAAPD94cGFja2V0IGJlZ2luPSLvu78iIGlkPSJXNU0wTXBDZWhpSHpyZVN6TlRjemtjOWQiPz4KPHg6eG1wbWV0YSB4bWxuczp4PSJhZG9iZTpuczptZXRhLyIgeDp4bXB0az0iQWRvYmUgWE1QIENvcmUgNS42LWMxMzggNzkuMTU5ODI0LCAyMDE2LzA5LzE0LTAxOjA5OjAxICAgICAgIkJggg==",
    "page_background_color": "#437BC6",
    "powered_by_duo": true
  }
}

Modify Live Custom Branding

Change effective custom branding settings. These settings can also be viewed and set in the Duo Admin Panel. Requires "Grant settings" API permission.

POST /admin/v1/branding

Parameters

Parameter	Required?	Description
`background_img`	Optional	A base64 encoded background image in PNG format, with maximum size less than 3MB and dimensions between 12 by 12 pixels and 3840 by 2160 pixels. Shown in Duo SSO and Duo Universal Prompt.
`card_accent_color`	Optional	A CSS hex color shown as the hash symbol (#) followed by three or six hexadecimal digits, which represents the colored line appearing at the top of the interactive user interface. Shown in Duo SSO and Universal Prompt.
`logo`	Optional	A base64 encoded logo image in PNG format, with maximum size less than 200KB and dimensions between 12 by 12 pixels and 500 by 500 pixels. Shown in Duo SSO, Duo Universal Prompt, and traditional prompt.
`page_background_color`	Optional	A CSS hex color shown as the hash symbol (#) followed by three or six hexadecimal digits, which represents the color appearing behind the user interface and any transparent background image. Shown in Duo SSO and Universal Prompt.
`powered_by_duo`	Optional	If `true`, Duo SSO, Duo Universal Prompt, and traditional prompt show the "Secured by Duo" branding. Otherwise, `false`.

Response Codes

Response	Meaning
200	The live branding settings were modified successfully. The settings objects are also returned (see Retrieve Live Custom Branding).
400	Invalid or missing parameters. For example, `card_accent_color` an invalid HTML hex code.
600	Incorrect PNG base64 encoding of logo or background images.

Response Format

Example Response

Retrieve Draft Custom Branding

Returns saved draft custom branding settings. These settings can also be viewed and set in the Duo Admin Panel. Requires "Grant settings" API permission.

GET /admin/v1/branding/draft

Parameters

This API endpoint has no parameters.

Response Codes

Response	Meaning
200	Success. Returns draft branding.

Response Format

Key Value

background_img A base64 encoded background image in PNG format. Shown in Duo SSO and Duo Universal Prompt.

card_accent_color A CSS hex color shown as the hash symbol (#) followed by three or six hexadecimal digits, which represents the colored line appearing at the top of the interactive user interface. Shown in Duo SSO and Universal Prompt.

draft_user

A list of test users who see draft branding (if configured) instead of live branding when using Duo SSO or Duo Universal Prompt.

Type Description

alias1...4 The user's username alias(es). Values included for backwards compatibility and reflect the same information as aliases.

aliases Map of the user's username alias(es). Up to eight aliases may exist.

created The user's creation date as a UNIX timestamp.

email The user's email address.

firstname The user's given name.

is_enrolled Is true if the user has a phone, hardware token, U2F token, WebAuthn security key, or other WebAuthn method available for authentication. Otherwise, false.

last_directory_sync An integer indicating the timestamp of the last update to the user via directory sync, or null if the user has never synced with an external directory or if the directory that originally created the user has been deleted from Duo.

last_login An integer indicating the last time this user logged in, as a Unix timestamp, or null if the user has not logged in.

lastname The user's surname.

notes Notes about this user.

realname The user's real name (or full name).

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 complete secondary authentication.
"locked out"	The user has been automatically locked out due to excessive authentication attempts.

user_id The user's ID.

username The user's username.

logo A base64 encoded logo image in PNG format. Shown in Duo SSO, Duo Universal Prompt, and traditional prompt.

page_background_color A CSS hex color shown as the hash symbol (#) followed by three or six hexadecimal digits, which represents the color appearing behind the user interface and any transparent background image. Shown in Duo SSO and Universal Prompt.

powered_by_duo If true, Duo SSO, Duo Universal Prompt, and traditional prompt show the "Secured by Duo" branding. Otherwise, false.

Example Response

{
  "stat": "OK",
  "response": {
    "background_image": "iVBORw0KGgoAAAANSUhEUgAABQAAAAMgCAYAAAB8mM/7AAABrmlUWHRYTUw6Y29tLmFkb2JlLnhtcAAAAAAAPD94cGFja2V0IGJlZ2luPSLvu78iIGlkPSJXNU0wTXBDZWhpSHpyZVN6TlRjemtjOWQiPz4KPHg6eG1wbWV0YSB4bWxuczp4PSJhZG9iZTpuczptZXRhLyIgeDp4bXB0az0iQWRvYmUgWE1QIENvcmUgNi4wLWMwMDYgNzkuMTY0NzUzLCAyMDIxLzAyLzE1LTExOjUyOjEzICAgICAgICAiPgogPHJkZjpSREYggg==",
    "card_accent_color": "#144A94",
    "draft_users": [{
        "alias1": "joe.smith",
        "alias2": "jsmith@example.com",
        "alias3": null,
        "alias4": null,
        "aliases": {
            "alias1": "joe.smith",
            "alias2": "jsmith@example.com"
        },
        "created": 1384275337,
        "email": "jsmith@example.com",
        "firstname": Joe,
        "is_enrolled": true,
        "last_directory_sync": 1384275337,
        "last_login": 1514922986,
        "lastname": Smith,
        "notes": "",
        "realname": "Joe Smith",
        "status": "active",
        "user_id": "DU3RP9I2WOC59VZX672N",
        "username": "jsmith",
    }],
    "logo": "iVBORw0KGgoAAAANSUhEUgAAARQAAAEwCAYAAAB2TY5ZAAAACXBIWXMAAAwHAAAMBwF2myPLAAA55mlUWHRYTUw6Y29tLmFkb2JlLnhtcAAAAAAAPD94cGFja2V0IGJlZ2luPSLvu78iIGlkPSJXNU0wTXBDZWhpSHpyZVN6TlRjemtjOWQiPz4KPHg6eG1wbWV0YSB4bWxuczp4PSJhZG9iZTpuczptZXRhLyIgeDp4bXB0az0iQWRvYmUgWE1QIENvcmUgNS42LWMxMzggNzkuMTU5ODI0LCAyMDE2LzA5LzE0LTAxOjA5OjAxICAgICAgIkJggg==",
    "page_background_color": "#437BC6",
    "powered_by_duo": true
  }
}

Modify Draft Custom Branding

Change draft custom branding settings. These settings can also be viewed and set in the Duo Admin Panel. Requires "Grant settings" API permission.

POST /admin/v1/branding/draft

Parameters

Parameter	Required?	Description
`background_img`	Optional	A base64 encoded background image in PNG format, with maximum size less than 3MB and dimensions between 12 by 12 pixels and 3840 by 2160 pixels. Shown in Duo SSO and Duo Universal Prompt.
`card_accent_color`	Optional	A CSS hex color shown as the hash symbol (#) followed by three or six hexadecimal digits, which represents the colored line appearing at the top of the interactive user interface. Shown in Duo SSO and Universal Prompt.
`logo`	Optional	A base64 encoded logo image in PNG format, with maximum size less than 200KB and dimensions between 12 by 12 pixels and 500 by 500 pixels. Shown in Duo SSO, Duo Universal Prompt, and traditional prompt.
`page_background_color`	Optional	A CSS hex color shown as the hash symbol (#) followed by three or six hexadecimal digits, which represents the color appearing below the user interface and beneath any transparent background image. Shown in Duo SSO and Universal Prompt.
`powered_by_duo`	Optional	If `true`, Duo SSO, Duo Universal Prompt, and traditional prompt show the "Secured by Duo" branding. Otherwise, `false`.
`user_ids`	Optional	A comma separated list of user IDs that will see saved draft branding in Duo SSO and Duo Universal Prompt.

Response Codes

Response	Meaning
200	The draft branding settings were modified successfully. The settings objects are also returned (see Retrieve Live Custom Branding).
400	Invalid or missing parameters. For example, `card_accent_color` an invalid HTML hex code.
600	Incorrect PNG base64 encoding of logo or background images.

Response Format

Example Response

Add Draft Custom Branding User by ID

Add a single user with ID user_id to the list of draft branding test users. Requires "Grant settings" API permission.

POST /admin/v1/branding/draft/users/[user_id]

Parameters

This API endpoint has no parameters.

Response Codes

Response	Meaning
200	The user was added to the draft branding user list successfully. The draft branding object is also returned (see Retrieve Draft Custom Branding).
404	No user was found with the given `user_id`.

Response Format

Example Response

Remove Draft Custom Branding User by ID

Remove a single user with ID user_id from the list of draft branding test users. Requires "Grant settings" API permission.

DELETE /admin/v1/branding/draft/users/[user_id]

Parameters

This API endpoint has no parameters.

Response Codes

Response	Meaning
200	The user was removed from the draft branding user list successfully. The draft branding object is also returned (see Retrieve Draft Custom Branding).
404	No user was found with the given `user_id`.

Response Format

Example Response

Publish Draft Custom Branding as Live Custom Branding

Replaces the current live custom branding with the draft custom branding for all users and then removes the draft branding. Requires "Grant settings" API permission.

POST /admin/v1/branding/draft/publish

Parameters

This API endpoint has no parameters.

Response Codes

Response	Meaning
200	Success.

Response Format

Example Response