OpenAPI Specification
openapi: 3.1.0
info:
title: Duo Admin Bulk Users API
description: The Duo Admin API provides programmatic access to the administrative functionality of Duo Security for managing users, groups, phones, hardware tokens, WebAuthn credentials, integrations, and bypass codes. Requests are authenticated using HMAC-SHA1 signed HTTP Basic credentials derived from your integration key and secret key.
version: v1
contact:
name: Duo Security
url: https://duo.com/docs/adminapi
servers:
- url: https://api-XXXXXXXX.duosecurity.com
description: Duo Admin API host (replace XXXXXXXX with your tenant identifier)
security:
- basicAuth: []
tags:
- name: Users
description: User account management
paths:
/admin/v1/users:
get:
operationId: listUsers
summary: List users
description: Returns a paged list of users.
tags:
- Users
parameters:
- name: username
in: query
schema:
type: string
- name: limit
in: query
schema:
type: integer
- name: offset
in: query
schema:
type: integer
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/UserListResponse'
post:
operationId: createUser
summary: Create user
description: Create a new user with the specified username.
tags:
- Users
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/UserCreate'
responses:
'200':
description: User created
content:
application/json:
schema:
$ref: '#/components/schemas/UserResponse'
/admin/v1/users/bulk_create:
post:
operationId: bulkCreateUsers
summary: Bulk create users
description: Create multiple users in a single request (max 100).
tags:
- Users
responses:
'200':
description: Bulk create result
/admin/v1/users/bulk_restore:
post:
operationId: bulkRestoreUsers
summary: Bulk restore users
description: Restore multiple users from the Trash.
tags:
- Users
responses:
'200':
description: Bulk restore result
/admin/v1/users/bulk_send_to_trash:
post:
operationId: bulkSendUsersToTrash
summary: Bulk send users to Trash
description: Send multiple users to the Trash.
tags:
- Users
responses:
'200':
description: Bulk trash result
/admin/v1/users/{user_id}:
parameters:
- name: user_id
in: path
required: true
schema:
type: string
get:
operationId: getUser
summary: Get user
description: Return the single user with the specified user_id.
tags:
- Users
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/UserResponse'
post:
operationId: updateUser
summary: Update user
description: Change the username, aliases, full name, status, or other attributes.
tags:
- Users
responses:
'200':
description: User updated
delete:
operationId: deleteUser
summary: Delete user
description: Delete the user with the specified user_id.
tags:
- Users
responses:
'200':
description: User deleted
/admin/v1/users/enroll:
post:
operationId: enrollUser
summary: Enroll user
description: Enroll a user and send an enrollment email.
tags:
- Users
responses:
'200':
description: Enrollment initiated
/admin/v1/users/{user_id}/groups:
parameters:
- name: user_id
in: path
required: true
schema:
type: string
get:
operationId: listUserGroups
summary: List user groups
description: Returns paged list of groups associated with a user.
tags:
- Users
responses:
'200':
description: Successful response
post:
operationId: associateUserGroup
summary: Associate group with user
tags:
- Users
responses:
'200':
description: Group associated
/admin/v1/users/{user_id}/groups/{group_id}:
parameters:
- name: user_id
in: path
required: true
schema:
type: string
- name: group_id
in: path
required: true
schema:
type: string
delete:
operationId: disassociateUserGroup
summary: Disassociate group from user
tags:
- Users
responses:
'200':
description: Group disassociated
/admin/v1/users/{user_id}/phones:
parameters:
- name: user_id
in: path
required: true
schema:
type: string
get:
operationId: listUserPhones
summary: List user phones
tags:
- Users
responses:
'200':
description: Successful response
post:
operationId: associateUserPhone
summary: Associate phone with user
tags:
- Users
responses:
'200':
description: Phone associated
/admin/v1/users/{user_id}/phones/{phone_id}:
parameters:
- name: user_id
in: path
required: true
schema:
type: string
- name: phone_id
in: path
required: true
schema:
type: string
delete:
operationId: disassociateUserPhone
summary: Disassociate phone from user
tags:
- Users
responses:
'200':
description: Phone disassociated
/admin/v1/users/{user_id}/tokens:
parameters:
- name: user_id
in: path
required: true
schema:
type: string
get:
operationId: listUserTokens
summary: List user hardware tokens
tags:
- Users
responses:
'200':
description: Successful response
post:
operationId: associateUserToken
summary: Associate hardware token with user
tags:
- Users
responses:
'200':
description: Token associated
/admin/v1/users/{user_id}/tokens/{token_id}:
parameters:
- name: user_id
in: path
required: true
schema:
type: string
- name: token_id
in: path
required: true
schema:
type: string
delete:
operationId: disassociateUserToken
summary: Disassociate hardware token from user
tags:
- Users
responses:
'200':
description: Token disassociated
/admin/v1/users/{user_id}/webauthncredentials:
parameters:
- name: user_id
in: path
required: true
schema:
type: string
get:
operationId: listUserWebAuthnCredentials
summary: List WebAuthn credentials for user
tags:
- Users
responses:
'200':
description: Successful response
/admin/v1/users/{user_id}/desktopauthenticators:
parameters:
- name: user_id
in: path
required: true
schema:
type: string
get:
operationId: listUserDesktopAuthenticators
summary: List desktop authenticators for user
tags:
- Users
responses:
'200':
description: Successful response
/admin/v1/users/directorysync:
get:
operationId: listUserDirectorySyncs
summary: List user directory syncs
tags:
- Users
responses:
'200':
description: Successful response
/admin/v1/users/directorysync/{directory_key}/syncuser:
parameters:
- name: directory_key
in: path
required: true
schema:
type: string
post:
operationId: syncDirectoryUser
summary: Sync directory user
description: Initiate sync for a specific user.
tags:
- Users
responses:
'200':
description: Sync initiated
/admin/v1/users/{user_id}/send_verification_push:
parameters:
- name: user_id
in: path
required: true
schema:
type: string
post:
operationId: sendVerificationPush
summary: Send verification Duo Push
tags:
- Users
responses:
'200':
description: Push sent
/admin/v1/users/{user_id}/verification_push_response:
parameters:
- name: user_id
in: path
required: true
schema:
type: string
get:
operationId: getVerificationPushResponse
summary: Retrieve verification push result
tags:
- Users
responses:
'200':
description: Successful response
components:
schemas:
UserListResponse:
type: object
properties:
stat:
type: string
response:
type: array
items:
$ref: '#/components/schemas/User'
UserCreate:
type: object
properties:
username:
type: string
realname:
type: string
email:
type: string
status:
type: string
enum:
- active
- bypass
- disabled
- locked out
- pending deletion
UserResponse:
type: object
properties:
stat:
type: string
response:
$ref: '#/components/schemas/User'
User:
type: object
properties:
user_id:
type: string
username:
type: string
realname:
type: string
email:
type: string
status:
type: string
created:
type: integer
last_login:
type: integer
securitySchemes:
basicAuth:
type: http
scheme: basic
description: HTTP Basic with HMAC-SHA1 signed credentials (integration key as user, signed signature as password).
externalDocs:
description: Duo Admin API Documentation
url: https://duo.com/docs/adminapi