Duo Security Users API

openapi: 3.2.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
  x-provenance:
    method: derived
    authored_by: API Evangelist
    derived_on: '2026-08-19'
    first_party: false
    provider_published: false
    source: Modelled from the provider's public HTML documentation.
    note: 'Not published by the provider. Probed 2026-08-19: no anonymously fetchable first-party contract. api.duosecurity.com answers 200 with an identical 130,977-byte HTML shell for invented paths — a soft 404, not a spec.'
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:
    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
    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
  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