openapi: 3.0.0
info:
  title: User Management
  description: |-
    Bandwidth's User Management

    ## Base URL

    `https://api.bandwidth.com/api/v1`
  version: 1.0.0
  contact:
    name: Bandwidth
  termsOfService: https://www.bandwidth.com/legal/terms-of-use-bandwidthcom-web-sites/
servers:
  - url: https://api.bandwidth.com/api/v1
paths:
  /users:
    get:
      tags:
        - Users
      summary: List Users
      description: >-
        Returns all the users that the requesting user has access to.


        Use the `Accept` request header to specify the response format:

        - `application/json` (default) — paginated JSON response

        - `text/csv` — CSV file download

        - `application/pdf` — PDF file download

        - `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` —
        Excel file download
      operationId: listUsers
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/afterCursor'
        - $ref: '#/components/parameters/email'
        - $ref: '#/components/parameters/firstName'
        - $ref: '#/components/parameters/lastName'
        - $ref: '#/components/parameters/phoneNumber'
        - $ref: '#/components/parameters/roleId'
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/globalAccountNumber'
        - $ref: '#/components/parameters/accountScope'
        - $ref: '#/components/parameters/status'
        - $ref: '#/components/parameters/createdBy'
        - $ref: '#/components/parameters/credentialSource'
        - $ref: '#/components/parameters/creationDate'
        - $ref: '#/components/parameters/lastModificationDate'
        - $ref: '#/components/parameters/lastAuthenticationDate'
      responses:
        '200':
          $ref: '#/components/responses/listUsersResponse'
        '400':
          $ref: '#/components/responses/genericBadRequestResponse'
        '401':
          $ref: '#/components/responses/genericUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/genericForbiddenResponse'
        '404':
          $ref: '#/components/responses/genericNotFoundResponse'
        '405':
          $ref: '#/components/responses/genericMethodNotAllowedResponse'
        '415':
          $ref: '#/components/responses/genericUnsupportedMediaTypeResponse'
        '429':
          $ref: '#/components/responses/genericTooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/genericRuntimeExceptionResponse'
    post:
      tags:
        - Users
      summary: Create User
      description: Creates a new user.
      operationId: createUser
      requestBody:
        $ref: '#/components/requestBodies/createUserRequest'
      responses:
        '201':
          $ref: '#/components/responses/createUserResponse'
        '400':
          $ref: '#/components/responses/genericBadRequestResponse'
        '401':
          $ref: '#/components/responses/genericUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/genericForbiddenResponse'
        '404':
          $ref: '#/components/responses/genericNotFoundResponse'
        '405':
          $ref: '#/components/responses/genericMethodNotAllowedResponse'
        '409':
          $ref: '#/components/responses/genericConflictResponse'
        '415':
          $ref: '#/components/responses/genericUnsupportedMediaTypeResponse'
        '429':
          $ref: '#/components/responses/genericTooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/genericRuntimeExceptionResponse'
  /users/{userId}:
    get:
      tags:
        - Users
      summary: Get User
      description: Returns the user with the given ID.
      operationId: getUser
      parameters:
        - $ref: '#/components/parameters/userId'
      responses:
        '200':
          $ref: '#/components/responses/getUserResponse'
        '400':
          $ref: '#/components/responses/genericBadRequestResponse'
        '401':
          $ref: '#/components/responses/genericUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/genericForbiddenResponse'
        '404':
          $ref: '#/components/responses/genericNotFoundResponse'
        '405':
          $ref: '#/components/responses/genericMethodNotAllowedResponse'
        '415':
          $ref: '#/components/responses/genericUnsupportedMediaTypeResponse'
        '429':
          $ref: '#/components/responses/genericTooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/genericRuntimeExceptionResponse'
    patch:
      tags:
        - Users
      summary: Update User
      description: Updates the user with the given ID.
      operationId: updateUser
      parameters:
        - $ref: '#/components/parameters/userId'
      requestBody:
        $ref: '#/components/requestBodies/updateUserRequest'
      responses:
        '200':
          $ref: '#/components/responses/updateUserResponse'
        '400':
          $ref: '#/components/responses/genericBadRequestResponse'
        '401':
          $ref: '#/components/responses/genericUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/genericForbiddenResponse'
        '404':
          $ref: '#/components/responses/genericNotFoundResponse'
        '405':
          $ref: '#/components/responses/genericMethodNotAllowedResponse'
        '409':
          $ref: '#/components/responses/genericConflictResponse'
        '415':
          $ref: '#/components/responses/genericUnsupportedMediaTypeResponse'
        '429':
          $ref: '#/components/responses/genericTooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/genericRuntimeExceptionResponse'
  /users/{userId}/reset-password:
    put:
      tags:
        - Users
      summary: Reset User Password
      description: >-
        Triggers a password reset flow for the specified user.  The user will
        receive an email with instructions to reset their password.
      operationId: resetUserPassword
      parameters:
        - $ref: '#/components/parameters/userId'
      responses:
        '204':
          $ref: '#/components/responses/noContentResponse'
        '400':
          $ref: '#/components/responses/genericBadRequestResponse'
        '401':
          $ref: '#/components/responses/genericUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/genericForbiddenResponse'
        '404':
          $ref: '#/components/responses/genericNotFoundResponse'
        '405':
          $ref: '#/components/responses/genericMethodNotAllowedResponse'
        '415':
          $ref: '#/components/responses/genericUnsupportedMediaTypeResponse'
        '429':
          $ref: '#/components/responses/genericTooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/genericRuntimeExceptionResponse'
  /users/{userId}/factors:
    get:
      tags:
        - MFA
      summary: List User MFA Factors
      description: List available MFA factors for the user
      operationId: listUserMfaFactors
      parameters:
        - $ref: '#/components/parameters/userId'
      responses:
        '200':
          $ref: '#/components/responses/listUserMfaFactorsResponse'
        '400':
          $ref: '#/components/responses/genericBadRequestResponse'
        '401':
          $ref: '#/components/responses/genericUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/genericForbiddenResponse'
        '404':
          $ref: '#/components/responses/genericNotFoundResponse'
        '405':
          $ref: '#/components/responses/genericMethodNotAllowedResponse'
        '415':
          $ref: '#/components/responses/genericUnsupportedMediaTypeResponse'
        '429':
          $ref: '#/components/responses/genericTooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/genericRuntimeExceptionResponse'
    post:
      tags:
        - MFA
      summary: Enroll User MFA Factor
      description: Starts the enrollment process for the specified MFA factor
      operationId: enrollUserMfaFactor
      parameters:
        - $ref: '#/components/parameters/userId'
      requestBody:
        $ref: '#/components/requestBodies/enrollUserMfaFactorRequest'
      responses:
        '200':
          $ref: '#/components/responses/enrollUserMfaFactorResponse'
        '400':
          $ref: '#/components/responses/genericBadRequestResponse'
        '401':
          $ref: '#/components/responses/genericUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/genericForbiddenResponse'
        '404':
          $ref: '#/components/responses/genericNotFoundResponse'
        '405':
          $ref: '#/components/responses/genericMethodNotAllowedResponse'
        '415':
          $ref: '#/components/responses/genericUnsupportedMediaTypeResponse'
        '429':
          $ref: '#/components/responses/genericTooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/genericRuntimeExceptionResponse'
  /users/{userId}/factors/{factorId}:
    delete:
      tags:
        - MFA
      summary: Reset User MFA Factor
      description: Unenrolls user from specified MFA Factor
      operationId: resetUserMfaFactor
      parameters:
        - $ref: '#/components/parameters/userId'
        - $ref: '#/components/parameters/factorId'
      responses:
        '204':
          $ref: '#/components/responses/noContentResponse'
        '400':
          $ref: '#/components/responses/genericBadRequestResponse'
        '401':
          $ref: '#/components/responses/genericUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/genericForbiddenResponse'
        '404':
          $ref: '#/components/responses/genericNotFoundResponse'
        '405':
          $ref: '#/components/responses/genericMethodNotAllowedResponse'
        '415':
          $ref: '#/components/responses/genericUnsupportedMediaTypeResponse'
        '429':
          $ref: '#/components/responses/genericTooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/genericRuntimeExceptionResponse'
    put:
      tags:
        - MFA
      summary: Activate User MFA factor
      description: Activates the specified MFA factor
      operationId: activateUserMfaFactor
      parameters:
        - $ref: '#/components/parameters/userId'
        - $ref: '#/components/parameters/factorId'
      requestBody:
        $ref: '#/components/requestBodies/activateUserMfaFactorRequest'
      responses:
        '200':
          $ref: '#/components/responses/activateUserMfaFactorResponse'
        '400':
          $ref: '#/components/responses/genericBadRequestResponse'
        '401':
          $ref: '#/components/responses/genericUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/genericForbiddenResponse'
        '404':
          $ref: '#/components/responses/genericNotFoundResponse'
        '405':
          $ref: '#/components/responses/genericMethodNotAllowedResponse'
        '415':
          $ref: '#/components/responses/genericUnsupportedMediaTypeResponse'
        '429':
          $ref: '#/components/responses/genericTooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/genericRuntimeExceptionResponse'
  /roles:
    get:
      tags:
        - Roles
      summary: List Roles
      description: Returns all the roles.
      operationId: listRoles
      responses:
        '200':
          $ref: '#/components/responses/listRolesResponse'
        '400':
          $ref: '#/components/responses/genericBadRequestResponse'
        '401':
          $ref: '#/components/responses/genericUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/genericForbiddenResponse'
        '404':
          $ref: '#/components/responses/genericNotFoundResponse'
        '405':
          $ref: '#/components/responses/genericMethodNotAllowedResponse'
        '415':
          $ref: '#/components/responses/genericUnsupportedMediaTypeResponse'
        '429':
          $ref: '#/components/responses/genericTooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/genericRuntimeExceptionResponse'
components:
  requestBodies:
    createUserRequest:
      description: Create user request body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/createUserRequest'
    updateUserRequest:
      description: Update user request body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/updateUserRequest'
    enrollUserMfaFactorRequest:
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/enrollUserMfaOtpRequest'
              - $ref: '#/components/schemas/enrollUserMfaEmailRequest'
    activateUserMfaFactorRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/activateUserMfaFactorRequest'
  responses:
    listUsersResponse:
      description: OK
      headers:
        Content-Disposition:
          description: >-
            Present when the response is a file download. Contains the suggested
            filename for the report.
          schema:
            type: string
            example: attachment; filename="user-report.csv"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/listUsersResponse'
          examples:
            listUsersResponseExample:
              $ref: '#/components/examples/listUsersResponseExample'
        text/csv:
          schema:
            type: string
            format: binary
            description: >-
              CSV file containing user data. Array fields (roles, accounts) are
              serialized as semicolon-delimited values within a single column.
          examples:
            listUsersCsvResponseExample:
              $ref: '#/components/examples/listUsersCsvResponseExample'
        application/pdf:
          schema:
            type: string
            format: binary
            description: PDF file containing user data
        application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
          schema:
            type: string
            format: binary
            description: Excel file containing user data
    getUserResponse:
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/userResponse'
          examples:
            getUserResponseExample:
              $ref: '#/components/examples/userResponseExample'
    createUserResponse:
      description: Created
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/userResponse'
          examples:
            createUserResponseExample:
              $ref: '#/components/examples/userResponseExample'
    updateUserResponse:
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/userResponse'
          examples:
            updateUserResponseExample:
              $ref: '#/components/examples/userResponseExample'
    listUserMfaFactorsResponse:
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/listUserMfaFactorsResponse'
          examples:
            listMfaFactorsResponseExample:
              $ref: '#/components/examples/listUserMfaFactorsResponseExample'
    activateUserMfaFactorResponse:
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/activateUserMfaFactorResponse'
          examples:
            activateUserMfaFactorResponseExample:
              $ref: '#/components/examples/activateUserMfaFactorResponseExample'
    enrollUserMfaFactorResponse:
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/enrollUserMfaFactorResponse'
          examples:
            enrollUserMfaFactorResponseExample:
              $ref: '#/components/examples/enrollUserMfaFactorResponseExample'
    listRolesResponse:
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/listRolesResponse'
          examples:
            listRolesResponseExample:
              $ref: '#/components/examples/listRolesResponseExample'
    noContentResponse:
      description: No Content
    genericBadRequestResponse:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            genericBadRequestResponseExample:
              $ref: '#/components/examples/genericBadRequestResponseExample'
    genericUnauthorizedResponse:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            genericUnauthorizedResponseExample:
              $ref: '#/components/examples/genericUnauthorizedResponseExample'
    genericForbiddenResponse:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            genericForbiddenResponseExample:
              $ref: '#/components/examples/genericForbiddenResponseExample'
    genericNotFoundResponse:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            GenericNotFoundResponseExample:
              $ref: '#/components/examples/genericNotFoundResponseExample'
    genericMethodNotAllowedResponse:
      description: Method Not Allowed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            genericMethodNotAllowedResponseExample:
              $ref: '#/components/examples/genericMethodNotAllowedResponseExample'
    genericConflictResponse:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            genericConflictResponseExample:
              $ref: '#/components/examples/genericConflictResponseExample'
    genericUnsupportedMediaTypeResponse:
      description: Unsupported Media Type
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            genericUnsupportedMediaTypeResponseExample:
              $ref: '#/components/examples/genericUnsupportedMediaTypeResponseExample'
    genericTooManyRequestsResponse:
      description: Too Many Requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            genericTooManyRequestsResponseExample:
              $ref: '#/components/examples/genericTooManyRequestsResponseExample'
    genericRuntimeExceptionResponse:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            genericRuntimeExceptionResponseExample:
              $ref: '#/components/examples/genericRuntimeExceptionResponseExample'
  schemas:
    createUserRequest:
      required:
        - userId
        - email
        - firstName
        - lastName
        - roles
        - accounts
        - accountScope
      type: object
      additionalProperties: false
      properties:
        userId:
          $ref: '#/components/schemas/userId'
        email:
          $ref: '#/components/schemas/email'
        firstName:
          $ref: '#/components/schemas/firstName'
        lastName:
          $ref: '#/components/schemas/lastName'
        phoneNumber:
          $ref: '#/components/schemas/phoneNumber'
        roles:
          $ref: '#/components/schemas/roles'
        accounts:
          $ref: '#/components/schemas/accounts'
        accountScope:
          $ref: '#/components/schemas/accountScopeEnum'
    updateUserRequest:
      type: object
      additionalProperties: false
      properties:
        email:
          $ref: '#/components/schemas/email'
        firstName:
          $ref: '#/components/schemas/firstName'
        lastName:
          $ref: '#/components/schemas/lastName'
        phoneNumber:
          $ref: '#/components/schemas/phoneNumber'
        roles:
          $ref: '#/components/schemas/roles'
        accounts:
          $ref: '#/components/schemas/accounts'
        accountScope:
          $ref: '#/components/schemas/accountScopeEnum'
        status:
          $ref: '#/components/schemas/statusTransitionsEnum'
    enrollUserMfaOtpRequest:
      type: object
      additionalProperties: false
      properties:
        factorType:
          $ref: '#/components/schemas/mfaFactorTypeEnum'
        provider:
          $ref: '#/components/schemas/mfaProviderEnum'
    enrollUserMfaEmailRequest:
      type: object
      additionalProperties: false
      required:
        - factorType
        - provider
        - profile
      properties:
        factorType:
          $ref: '#/components/schemas/mfaFactorTypeEnum'
        provider:
          $ref: '#/components/schemas/mfaProviderEnum'
        profile:
          $ref: '#/components/schemas/enrollMfaEmailProfile'
    activateUserMfaFactorRequest:
      type: object
      additionalProperties: false
      required:
        - passCode
      properties:
        passCode:
          $ref: '#/components/schemas/mfaPassCode'
    userResponse:
      type: object
      additionalProperties: false
      required:
        - links
        - data
        - errors
      properties:
        links:
          type: array
          items:
            $ref: '#/components/schemas/link'
          example: []
        data:
          $ref: '#/components/schemas/user'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/error'
          example: []
    listUsersResponse:
      type: object
      additionalProperties: false
      required:
        - links
        - data
        - errors
        - page
      properties:
        links:
          type: array
          items:
            $ref: '#/components/schemas/link'
          example: []
        data:
          type: array
          items:
            $ref: '#/components/schemas/user'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/error'
          example: []
        page:
          $ref: '#/components/schemas/page'
    listUserMfaFactorsResponse:
      type: object
      additionalProperties: false
      required:
        - links
        - data
        - errors
      properties:
        links:
          type: array
          items:
            $ref: '#/components/schemas/link'
          example: []
        data:
          type: array
          items:
            $ref: '#/components/schemas/mfaFactor'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/error'
          example: []
    enrollUserMfaFactorResponse:
      type: object
      additionalProperties: false
      required:
        - links
        - data
        - errors
      properties:
        links:
          type: array
          items:
            $ref: '#/components/schemas/link'
          example: []
        data:
          type: object
          additionalProperties: false
          required:
            - id
            - status
          properties:
            id:
              $ref: '#/components/schemas/mfaFactorId'
            status:
              $ref: '#/components/schemas/mfaFactorStatusEnum'
            qrCode:
              $ref: '#/components/schemas/mfaQrCode'
            sharedSecret:
              $ref: '#/components/schemas/mfaSharedSecret'
            factorType:
              $ref: '#/components/schemas/mfaFactorTypeEnum'
            provider:
              $ref: '#/components/schemas/mfaProviderEnum'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/error'
          example: []
    activateUserMfaFactorResponse:
      type: object
      additionalProperties: false
      required:
        - links
        - data
        - errors
      properties:
        links:
          type: array
          items:
            $ref: '#/components/schemas/link'
          example: []
        data:
          $ref: '#/components/schemas/mfaFactor'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/error'
          example: []
    listRolesResponse:
      type: object
      additionalProperties: false
      required:
        - links
        - data
        - errors
      properties:
        links:
          type: array
          items:
            $ref: '#/components/schemas/link'
          example: []
        data:
          type: array
          items:
            $ref: '#/components/schemas/role'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/error'
          example: []
    errorResponse:
      required:
        - links
        - data
        - errors
      type: object
      additionalProperties: false
      properties:
        links:
          type: array
          items:
            $ref: '#/components/schemas/link'
          example: []
        data:
          type: object
          nullable: true
        errors:
          type: array
          items:
            $ref: '#/components/schemas/error'
          example: []
    link:
      title: link
      type: object
      additionalProperties: false
      properties:
        href:
          type: string
          description: The URI of the link
          example: /api/v1/users
        rel:
          type: string
          description: The relationship of the link to the resource
          example: self
        method:
          type: string
          description: The HTTP method to use when following the link
          example: GET
    error:
      title: error
      type: object
      additionalProperties: false
      properties:
        type:
          type: string
          description: A short human-readable summary of the problem encountered
          example: Error
        description:
          type: string
          description: >-
            A human-readable detailed description that SHOULD be specific to the
            problem encountered
          example: There was a problem with your request. Please try again
        code:
          type: string
          description: A User Management API specific error code
          example: E0001
        source:
          type: object
          description: Information about the source of the error
          additionalProperties: false
          properties:
            field:
              type: string
              description: The field in the request that caused the error
              example: lastName
            parameter:
              type: string
              description: The parameter in the query that caused the error
              example: firstName
        meta:
          type: object
          description: Additional metadata about the error
          additionalProperties: false
          properties:
            traceId:
              type: string
              description: A unique identifier for the error
              example: '123456789'
    page:
      type: object
      properties:
        pageSize:
          type: number
          description: The number of items returned in the current page.
          example: 50
    user:
      required:
        - userId
        - email
        - firstName
        - lastName
        - roles
        - accounts
        - accountScope
        - status
        - createdBy
        - creationDate
        - lastModificationDate
        - credentialSource
      type: object
      additionalProperties: false
      properties:
        userId:
          $ref: '#/components/schemas/userId'
        email:
          $ref: '#/components/schemas/email'
        firstName:
          $ref: '#/components/schemas/firstName'
        lastName:
          $ref: '#/components/schemas/lastName'
        phoneNumber:
          $ref: '#/components/schemas/phoneNumber'
        roles:
          $ref: '#/components/schemas/roles'
        accounts:
          $ref: '#/components/schemas/accounts'
        globalAccountNumbers:
          $ref: '#/components/schemas/globalAccountNumbers'
        accountScope:
          $ref: '#/components/schemas/accountScopeEnum'
        status:
          $ref: '#/components/schemas/statusEnum'
        createdBy:
          $ref: '#/components/schemas/createdBy'
        credentialSource:
          $ref: '#/components/schemas/credentialSourceEnum'
        creationDate:
          $ref: '#/components/schemas/creationDate'
        lastModificationDate:
          $ref: '#/components/schemas/lastModificationDate'
        lastAuthenticationDate:
          $ref: '#/components/schemas/lastAuthenticationDate'
    userId:
      type: string
      description: Unique identifier of the user
      pattern: ^[A-Za-z0-9@._+-]*$
      minLength: 4
      maxLength: 45
      example: testUser
    email:
      type: string
      format: email
      description: The email of the user
      example: kstone@bandwidth.com
      minLength: 5
      maxLength: 100
    firstName:
      type: string
      description: The first name of the user
      example: Nicolas
    lastName:
      type: string
      description: The last name of the user
      example: Cage
    phoneNumber:
      type: string
      description: User's phone number in E.164 `+19195551234` format
      example: '+19195551234'
    accountScopeEnum:
      type: string
      description: The scope of the user
      example: ACCOUNT_ADMIN
      enum:
        - ACCOUNT
        - ACCOUNT_ADMIN
    globalAccountNumber:
      type: string
      description: A unique identifier for a global account
      pattern: BW-[0-9]{7}
      example: BW-1234567
    globalAccountNumbers:
      type: array
      description: The global account numbers associated with the user
      items:
        $ref: '#/components/schemas/globalAccountNumber'
    statusEnum:
      type: string
      description: The status of the user
      example: ACTIVE
      enum:
        - STAGED
        - PROVISIONED
        - ACTIVE
        - PASSWORD_EXPIRED
        - LOCKED_OUT
        - RECOVERY
        - SUSPENDED
        - DEPROVISIONED
    statusTransitionsEnum:
      type: string
      description: Valid statuses that a user can transition to
      example: ACTIVE
      enum:
        - ACTIVE
        - SUSPENDED
        - DEPROVISIONED
    createdBy:
      type: string
      description: The principal that created this user (Username or Client ID)
      example: adminUser
    creationDate:
      type: string
      format: date-time
      description: The date and time the user was created
      example: '2026-01-01T12:00:00Z'
    lastModificationDate:
      type: string
      format: date-time
      description: The date and time the user was last modified
      example: '2026-01-02T12:00:00Z'
    lastAuthenticationDate:
      type: string
      format: date-time
      description: The date and time of the last authentication
      example: '2026-01-02T12:00:00Z'
    credentialSourceEnum:
      type: string
      description: The credential source for the user
      example: PASSWORD
      enum:
        - PASSWORD
        - SSO
        - SSO_PASSWORD
    accountId:
      type: string
      description: A unique identifier for an account
      pattern: ^[A-Za-z0-9]{1,15}$
      example: '1232131'
    accounts:
      type: array
      items:
        $ref: '#/components/schemas/accountId'
    roleId:
      type: string
      description: Identifier of the role
      pattern: ^[A-Za-z0-9 _-]{4,60}$
      example: testRole
    roles:
      type: array
      items:
        $ref: '#/components/schemas/roleId'
    role:
      required:
        - id
        - name
        - description
      type: object
      additionalProperties: false
      properties:
        id:
          $ref: '#/components/schemas/roleId'
        name:
          $ref: '#/components/schemas/roleName'
        description:
          $ref: '#/components/schemas/roleDescription'
    roleName:
      type: string
      description: Name of the role
      example: Test Role
    roleDescription:
      type: string
      description: Description of the role
      example: This role gives you testing abilities
    mfaFactorId:
      type: string
      description: The unique identifier of the MFA Factor
      example: chf20l33Ks8U2Zjba0g4
    mfaFactorTypeEnum:
      type: string
      description: The MFA factor type
      enum:
        - TOTP
        - EMAIL
      example: TOTP
    mfaProviderEnum:
      type: string
      description: The MFA factor provider
      enum:
        - OKTA
        - GOOGLE
      example: OKTA
    mfaFactorDisplayName:
      type: string
      description: The display name of the MFA factor
      example: Authenticator App
    mfaFactorStatusEnum:
      type: string
      description: The enrollment status of the MFA factor
      enum:
        - NOT_SETUP
        - PENDING_ACTIVATION
        - ENROLLED
        - ACTIVE
        - INACTIVE
        - EXPIRED
      example: NOT_SETUP
    mfaSharedSecret:
      type: string
      description: The MFA factor's unique secret key for prover
      example: JBTWGV22G4ZGKV3N
    mfaQrCodeHref:
      type: string
      description: The location to find the QR Code image
      example: https://upload.wikimedia.org/wikipedia/commons/5/5e/QR_Code_example.png
    mfaQrCodeType:
      type: string
      description: The type of image the QR Code will be
      example: image/png
    mfaQrCode:
      type: object
      additionalProperties: false
      required:
        - href
        - type
      properties:
        href:
          $ref: '#/components/schemas/mfaQrCodeHref'
        type:
          $ref: '#/components/schemas/mfaQrCodeType'
    mfaFactorRequired:
      type: boolean
      description: Whether or not the mfa is required to be enrolled
      example: true
    mfaFactor:
      type: object
      additionalProperties: false
      required:
        - displayName
        - factorType
        - provider
        - status
        - required
      properties:
        id:
          $ref: '#/components/schemas/mfaFactorId'
        factorType:
          $ref: '#/components/schemas/mfaFactorTypeEnum'
        provider:
          $ref: '#/components/schemas/mfaProviderEnum'
        status:
          $ref: '#/components/schemas/mfaFactorStatusEnum'
        required:
          $ref: '#/components/schemas/mfaFactorRequired'
        displayName:
          $ref: '#/components/schemas/mfaFactorDisplayName'
    enrollMfaEmailProfile:
      type: object
      additionalProperties: false
      required:
        - email
      properties:
        email:
          $ref: '#/components/schemas/email'
    mfaPassCode:
      type: string
      description: One Time PassCode
      example: '123456'
    sort:
      type: string
      enum:
        - ASC
        - DESC
      description: Sort order, either ascending (ASC) or descending (DESC)
    emailQueryParam:
      type: object
      properties:
        eq:
          type: string
          description: Equal to the specified email address.
        startsWith:
          type: string
          description: Starts with the specified string.
        contains:
          type: string
          description: Contains the specified string.
        sort:
          $ref: '#/components/schemas/sort'
      example:
        startsWith: mike
    nameQueryParam:
      type: object
      properties:
        eq:
          type: string
          description: Equal to the specified name.
        startsWith:
          type: string
          description: Starts with the specified string.
        contains:
          type: string
          description: Contains the specified string.
        sort:
          $ref: '#/components/schemas/sort'
      example:
        startsWith: John
    phoneNumberQueryParam:
      type: object
      properties:
        eq:
          type: string
          description: Equal to the specified phone number.
        startsWith:
          type: string
          description: Starts with the specified string.
        sort:
          $ref: '#/components/schemas/sort'
      example:
        startsWith: '123'
    roleIdQueryParam:
      type: object
      properties:
        eq:
          type: string
          description: Equal to the specified role ID.
      example:
        eq: httpVoice
    accountIdQueryParam:
      type: object
      properties:
        eq:
          type: string
          description: Equal to the specified account ID.
      example:
        eq: '1232131'
    globalAccountNumberQueryParam:
      type: object
      properties:
        eq:
          type: string
          description: Equal to the specified global account number.
        sort:
          $ref: '#/components/schemas/sort'
      example:
        eq: BW-1234567
    accountScopeQueryParam:
      type: object
      properties:
        eq:
          $ref: '#/components/schemas/accountScopeEnum'
        sort:
          $ref: '#/components/schemas/sort'
      example:
        eq: ACCOUNT_ADMIN
    statusQueryParam:
      type: object
      properties:
        eq:
          $ref: '#/components/schemas/statusEnum'
        sort:
          $ref: '#/components/schemas/sort'
      example:
        eq: ACTIVE
    createdByQueryParam:
      type: object
      properties:
        eq:
          type: string
          description: Equal to the specified creator.
        startsWith:
          type: string
          description: Starts with the specified string.
        sort:
          $ref: '#/components/schemas/sort'
      example:
        startsWith: mike
    credentialSourceQueryParam:
      type: object
      properties:
        eq:
          $ref: '#/components/schemas/credentialSourceEnum'
        sort:
          $ref: '#/components/schemas/sort'
      example:
        eq: PASSWORD
    dateQueryParam:
      type: object
      properties:
        gte:
          type: string
          format: date-time
          description: Greater than or equal to the specified date and time.
        lte:
          type: string
          format: date-time
          description: Less than or equal to the specified date and time.
        sort:
          $ref: '#/components/schemas/sort'
      example:
        gte: '2025-01-01T00:00:00Z'
        lte: '2025-12-31T23:59:59Z'
  parameters:
    userId:
      in: path
      name: userId
      description: Unique identifier of the user
      required: true
      schema:
        $ref: '#/components/schemas/userId'
    factorId:
      in: path
      name: factorId
      description: Unique identifier of the MFA Factor
      required: true
      schema:
        $ref: '#/components/schemas/mfaFactorId'
    afterCursor:
      name: afterCursor
      in: query
      required: false
      description: >-
        The cursor to use for pagination. This is the value of the `next` link
        from the previous response.
      schema:
        type: string
    limit:
      name: limit
      in: query
      required: false
      description: The maximum number of items to return. Defaults to 100.
      schema:
        type: integer
        default: 100
    email:
      name: email
      in: query
      required: false
      description: The email address of the user.
      style: deepObject
      schema:
        $ref: '#/components/schemas/emailQueryParam'
    firstName:
      name: firstName
      in: query
      required: false
      description: The first name of the user.
      style: deepObject
      schema:
        $ref: '#/components/schemas/nameQueryParam'
    lastName:
      name: lastName
      in: query
      required: false
      description: The last name of the user.
      style: deepObject
      schema:
        $ref: '#/components/schemas/nameQueryParam'
    phoneNumber:
      name: phoneNumber
      in: query
      required: false
      description: The phone number of the user.
      style: deepObject
      schema:
        $ref: '#/components/schemas/phoneNumberQueryParam'
    roleId:
      name: roleId
      in: query
      required: false
      description: A role id assigned to a user.
      style: deepObject
      schema:
        $ref: '#/components/schemas/roleIdQueryParam'
    accountId:
      name: accountId
      in: query
      required: false
      description: An account id assigned to a user.
      style: deepObject
      schema:
        $ref: '#/components/schemas/accountIdQueryParam'
    globalAccountNumber:
      name: globalAccountNumber
      in: query
      required: false
      description: The global account number assigned to a user.
      style: deepObject
      schema:
        $ref: '#/components/schemas/globalAccountNumberQueryParam'
    accountScope:
      name: accountScope
      in: query
      required: false
      description: The account scope assigned to a user.
      style: deepObject
      schema:
        $ref: '#/components/schemas/accountScopeQueryParam'
    status:
      name: status
      in: query
      required: false
      description: The status of the user.
      style: deepObject
      schema:
        $ref: '#/components/schemas/statusQueryParam'
    createdBy:
      name: createdBy
      in: query
      required: false
      description: The principal that created the user.
      style: deepObject
      schema:
        $ref: '#/components/schemas/createdByQueryParam'
    credentialSource:
      name: credentialSource
      in: query
      required: false
      description: The source of the user's credentials.
      style: deepObject
      schema:
        $ref: '#/components/schemas/credentialSourceQueryParam'
    creationDate:
      name: creationDate
      in: query
      required: false
      description: The date and time when the user was created.
      style: deepObject
      schema:
        $ref: '#/components/schemas/dateQueryParam'
    lastModificationDate:
      name: lastModificationDate
      in: query
      required: false
      description: The date and time when the user was last modified.
      style: deepObject
      schema:
        $ref: '#/components/schemas/dateQueryParam'
    lastAuthenticationDate:
      name: lastAuthenticationDate
      in: query
      required: false
      description: The date and time when the user last authenticated.
      style: deepObject
      schema:
        $ref: '#/components/schemas/dateQueryParam'
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: jwt
  examples:
    userResponseExample:
      value:
        links: []
        data:
          userId: testUser
          email: mike@bandwidth.com
          firstName: Mike
          lastName: Wazowski
          phoneNumber: '1234567890'
          roles:
            - httpVoice
          accounts:
            - '1232131'
          globalAccountNumbers:
            - BW-1234567
          accountScope: ACCOUNT_ADMIN
          status: ACTIVE
          createdBy: adminUser
          creationDate: '2026-01-01T12:00:00Z'
          lastModificationDate: '2026-01-02T12:00:00Z'
          lastAuthenticationDate: '2026-01-02T12:00:00Z'
          credentialSource: PASSWORD
        errors: []
    listUsersResponseExample:
      value:
        links: []
        data:
          - userId: mikew
            email: mike@bandwidth.com
            firstName: Mike
            lastName: Wazowski
            phoneNumber: '+11112223333'
            roles:
              - httpVoice
            accounts:
              - '1232131'
            globalAccountNumbers:
              - BW-1234567
            accountScope: ACCOUNT_ADMIN
            status: ACTIVE
            createdBy: adminUser
            creationDate: '2026-01-01T12:00:00Z'
            lastModificationDate: '2026-01-02T12:00:00Z'
            lastAuthenticationDate: '2026-01-02T12:00:00Z'
            credentialSource: PASSWORD
          - userId: sully
            email: sully@bandwidth.com
            firstName: James
            lastName: Sullivan
            phoneNumber: '+19998887777'
            roles:
              - httpVoice
            accounts:
              - '1232131'
            globalAccountNumbers:
              - BW-1234567
            accountScope: ACCOUNT
            status: ACTIVE
            createdBy: mikew
            creationDate: '2026-01-03T12:00:00Z'
            lastModificationDate: '2026-01-04T12:00:00Z'
            lastAuthenticationDate: '2026-01-04T12:00:00Z'
            credentialSource: PASSWORD
        errors: []
        page:
          pageSize: 2
    listUsersCsvResponseExample:
      value: >
        userId,email,firstName,lastName,phoneNumber,roles,accounts,gan,accountScope,status,createdBy,credentialSource,creationDate,lastModificationDate,lastAuthenticationDate

        mikew,mike@bandwidth.com,Mike,Wazowski,+11112223333,httpVoice;adminRole,1232131;9876543,GAN123456,ACCOUNT_ADMIN,ACTIVE,adminUser,PASSWORD,2026-01-01T12:00:00Z,2026-01-02T12:00:00Z,2026-01-02T12:00:00Z
    listUserMfaFactorsResponseExample:
      value:
        links: []
        data:
          - factorType: TOTP
            provider: OKTA
            status: NOT_SETUP
            required: false
            displayName: Okta Verify
          - factorType: TOTP
            provider: GOOGLE
            status: NOT_SETUP
            required: false
            displayName: Authenticator App
          - id: chf20l33Ks8U2Zjba0g4
            factorType: EMAIL
            provider: OKTA
            status: ACTIVE
            required: true
            displayName: Email
        errors: []
    enrollUserMfaFactorResponseExample:
      value:
        links: []
        data:
          id: chf20l33Ks8U2Zjba0g4
          factorType: TOTP
          provider: GOOGLE
          status: PENDING_ACTIVATION
          qrCode:
            href: >-
              https://upload.wikimedia.org/wikipedia/commons/5/5e/QR_Code_example.png
            type: image/png
          sharedSecret: JBTWGV22G4ZGKV3N
        errors: []
    activateUserMfaFactorResponseExample:
      value:
        links: []
        data:
          id: chf20l33Ks8U2Zjba0g4
          factorType: TOTP
          provider: GOOGLE
          status: ACTIVE
          required: true
          displayName: Google Authenticator
        errors: []
    listRolesResponseExample:
      value:
        links: []
        data:
          - id: adminRole
            name: Administrator
            description: This role gives you full access to all resources
          - id: httpVoice
            name: HTTP Voice Role
            description: This role gives you access to HTTP Voice resources
        errors: []
    genericBadRequestResponseExample:
      value:
        links: []
        data: null
        errors:
          - type: validation
            description: lastName is a required field
            code: 4ALL0001
            source:
              field: lastName
            meta:
              traceId: '123456789'
    genericUnauthorizedResponseExample:
      value:
        links: []
        data: null
        errors:
          - type: unauthorized
            description: Authentication credentials are missing or invalid
            code: 4ALL0002
            meta:
              traceId: '123456789'
    genericForbiddenResponseExample:
      value:
        links: []
        data: null
        errors:
          - type: forbidden
            description: You do not have permission to access this resource
            code: 4ALL0003
            meta:
              traceId: '123456789'
    genericNotFoundResponseExample:
      value:
        links: []
        data: null
        errors:
          - type: not-found
            description: The specified resource could not be found
            code: 4ALL0004
            meta:
              traceId: '123456789'
    genericMethodNotAllowedResponseExample:
      value:
        links: []
        data: null
        errors:
          - type: method-not-allowed
            description: The HTTP method used is not allowed for this resource
            code: 4ALL0005
            meta:
              traceId: '123456789'
    genericConflictResponseExample:
      value:
        links: []
        data: null
        errors:
          - type: conflict
            description: >-
              The request could not be completed due to a conflict with the
              current state of the resource
            code: 4ALL0008
            source:
              field: userId
            meta:
              traceId: '123456789'
    genericUnsupportedMediaTypeResponseExample:
      value:
        links: []
        data: null
        errors:
          - type: unsupported-media-type
            description: The media type of the request is not supported
            code: 4ALL0006
            meta:
              traceId: '123456789'
    genericTooManyRequestsResponseExample:
      value:
        links: []
        data: null
        errors:
          - type: too-many-requests
            description: You have exceeded the rate limit for this resource
            code: 4ALL0007
            meta:
              traceId: '123456789'
    genericRuntimeExceptionResponseExample:
      value:
        links: []
        data: null
        errors:
          - type: internal-error
            description: An unexpected error occurred, please try again later
            code: 5ALL0001
            meta:
              traceId: '123456789'
security:
  - Bearer: []
tags:
  - name: Users
  - name: MFA
  - name: Roles
