FusionAuth User API

openapi: 3.0.3
info:
  version: 1.66.0
  title: FusionAuth Api Key User API
  description: This is a FusionAuth server. Find out more at [https://fusionauth.io](https://fusionauth.io). You need to [set up an API key](https://fusionauth.io/docs/v1/tech/apis/authentication#managing-api-keys) in the FusionAuth instance you are using to test out the API calls.
  license:
    name: Apache2
servers:
- url: http://localhost:9011
- url: https://sandbox.fusionauth.io
security:
- ApiKeyAuth: []
tags:
- name: User
paths:
  /api/user:
    post:
      description: Creates a user. You can optionally specify an Id for the user, if not provided one will be generated.
      operationId: createUser
      parameters:
      - in: header
        name: X-FusionAuth-TenantId
        description: The unique Id of the tenant used to scope this API request. Only required when there is more than one tenant and the API key is not tenant-scoped.
        required: false
        schema:
          type: string
          format: UUID
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      tags:
      - User
    get:
      description: Retrieves the user by a verificationId. The intended use of this API is to retrieve a user after the forgot password workflow has been initiated and you may not know the user's email or username. OR Retrieves the user for the given username. OR Retrieves the user for the loginId, using specific loginIdTypes. OR Retrieves the user for the loginId. The loginId can be either the username or the email. OR Retrieves the user for the given email. OR Retrieves the user by a change password Id. The intended use of this API is to retrieve a user after the forgot password workflow has been initiated and you may not know the user's email or username.
      operationId: retrieveUser
      parameters:
      - name: verificationId
        in: query
        schema:
          type: string
        description: The unique verification Id that has been set on the user object.
      - in: header
        name: X-FusionAuth-TenantId
        description: The unique Id of the tenant used to scope this API request. Only required when there is more than one tenant and the API key is not tenant-scoped.
        required: false
        schema:
          type: string
          format: UUID
      - name: username
        in: query
        schema:
          type: string
        description: The username of the user.
      - name: loginId
        in: query
        schema:
          type: string
        description: The email or username of the user.
      - name: loginIdTypes
        in: query
        schema:
          type: array
          items:
            type: string
        description: The identity types that FusionAuth will compare the loginId to.
      - name: email
        in: query
        schema:
          type: string
        description: The email of the user.
      - name: changePasswordId
        in: query
        schema:
          type: string
        description: The unique change password Id that was sent via email or returned by the Forgot Password API.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      tags:
      - User
  /api/user/action:
    post:
      description: Takes an action on a user. The user being actioned is called the "actionee" and the user taking the action is called the "actioner". Both user ids are required in the request object.
      operationId: actionUserWithId
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActionRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      tags:
      - User
    get:
      description: Retrieves all the actions for the user with the given Id that are currently inactive. An inactive action means one that is time based and has been canceled or has expired, or is not time based. OR Retrieves all the actions for the user with the given Id that are currently active. An active action means one that is time based and has not been canceled, and has not ended. OR Retrieves all the actions for the user with the given Id that are currently preventing the User from logging in. OR Retrieves all the actions for the user with the given Id. This will return all time based actions that are active, and inactive as well as non-time based actions.
      operationId: retrieveUserActioning
      parameters:
      - name: userId
        in: query
        schema:
          type: string
        description: The Id of the user to fetch the actions for.
      - name: active
        in: query
        schema:
          type: string
      - name: preventingLogin
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      tags:
      - User
  /api/user/action/{actionId}:
    delete:
      description: Cancels the user action.
      operationId: cancelActionWithId
      parameters:
      - name: actionId
        in: path
        schema:
          type: string
        required: true
        description: The action Id of the action to cancel.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActionRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      tags:
      - User
    put:
      description: Modifies a temporal user action by changing the expiration of the action and optionally adding a comment to the action.
      operationId: modifyActionWithId
      parameters:
      - name: actionId
        in: path
        schema:
          type: string
        required: true
        description: The Id of the action to modify. This is technically the user action log Id.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActionRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      tags:
      - User
    get:
      description: Retrieves a single action log (the log of a user action that was taken on a user previously) for the given Id.
      operationId: retrieveActionWithId
      parameters:
      - name: actionId
        in: path
        schema:
          type: string
        required: true
        description: The Id of the action to retrieve.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      tags:
      - User
  /api/user/bulk:
    delete:
      description: Deletes the users with the given Ids, or users matching the provided JSON query or queryString. The order of preference is Ids, query and then queryString, it is recommended to only provide one of the three for the request.  This method can be used to deactivate or permanently delete (hard-delete) users based upon the hardDelete boolean in the request body. Using the dryRun parameter you may also request the result of the action without actually deleting or deactivating any users. OR Deactivates the users with the given Ids.
      operationId: deleteUserBulk
      parameters:
      - name: userIds
        in: query
        schema:
          type: string
        description: The ids of the users to deactivate.
      - name: dryRun
        in: query
        schema:
          type: string
      - name: hardDelete
        in: query
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserDeleteRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDeleteResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      tags:
      - User
  /api/user/change-password:
    post:
      description: 'Changes a user''s password using their access token (JWT) instead of the changePasswordId A common use case for this method will be if you want to allow the user to change their own password.  Remember to send refreshToken in the request body if you want to get a new refresh token when login using the returned oneTimePassword. OR Changes a user''s password using their identity (loginId and password). Using a loginId instead of the changePasswordId bypasses the email verification and allows a password to be changed directly without first calling the #forgotPassword method.'
      operationId: createUserChangePassword
      security:
      - BearerAuth: []
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangePasswordRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChangePasswordResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      tags:
      - User
    get:
      description: Check to see if the user must obtain a Trust Request Id in order to complete a change password request. When a user has enabled Two-Factor authentication, before you are allowed to use the Change Password API to change your password, you must obtain a Trust Request Id by completing a Two-Factor Step-Up authentication.  An HTTP status code of 400 with a general error code of [TrustTokenRequired] indicates that a Trust Token is required to make a POST request to this API. OR Check to see if the user must obtain a Trust Request Id in order to complete a change password request. When a user has enabled Two-Factor authentication, before you are allowed to use the Change Password API to change your password, you must obtain a Trust Request Id by completing a Two-Factor Step-Up authentication.  An HTTP status code of 400 with a general error code of [TrustTokenRequired] indicates that a Trust Token is required to make a POST request to this API. OR Check to see if the user must obtain a Trust Request Id in order to complete a change password request. When a user has enabled Two-Factor authentication, before you are allowed to use the Change Password API to change your password, you must obtain a Trust Request Id by completing a Two-Factor Step-Up authentication.  An HTTP status code of 400 with a general error code of [TrustTokenRequired] indicates that a Trust Token is required to make a POST request to this API. OR Check to see if the user must obtain a Trust Request Id in order to complete a change password request. When a user has enabled Two-Factor authentication, before you are allowed to use the Change Password API to change your password, you must obtain a Trust Request Id by completing a Two-Factor Step-Up authentication.  An HTTP status code of 400 with a general error code of [TrustTokenRequired] indicates that a Trust Token is required to make a POST request to this API. OR Check to see if the user must obtain a Trust Token Id in order to complete a change password request. When a user has enabled Two-Factor authentication, before you are allowed to use the Change Password API to change your password, you must obtain a Trust Token by completing a Two-Factor Step-Up authentication.  An HTTP status code of 400 with a general error code of [TrustTokenRequired] indicates that a Trust Token is required to make a POST request to this API. OR Check to see if the user must obtain a Trust Token Id in order to complete a change password request. When a user has enabled Two-Factor authentication, before you are allowed to use the Change Password API to change your password, you must obtain a Trust Token by completing a Two-Factor Step-Up authentication.  An HTTP status code of 400 with a general error code of [TrustTokenRequired] indicates that a Trust Token is required to make a POST request to this API.
      operationId: retrieveUserChangePassword
      parameters:
      - name: loginId
        in: query
        schema:
          type: string
        description: The loginId of the User that you intend to change the password for.
      - name: loginIdTypes
        in: query
        schema:
          type: array
          items:
            type: string
        description: The identity types that FusionAuth will compare the loginId to.
      - name: ipAddress
        in: query
        schema:
          type: string
        description: IP address of the user changing their password. This is used for MFA risk assessment.
      responses:
        '200':
          description: Success
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      tags:
      - User
  /api/user/change-password/{changePasswordId}:
    post:
      description: Changes a user's password using the change password Id. This usually occurs after an email has been sent to the user and they clicked on a link to reset their password.  As of version 1.32.2, prefer sending the changePasswordId in the request body. To do this, omit the first parameter, and set the value in the request body.
      operationId: changePasswordWithId
      parameters:
      - name: changePasswordId
        in: path
        schema:
          type: string
        required: true
        description: The change password Id used to find the user. This value is generated by FusionAuth once the change password workflow has been initiated.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangePasswordRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChangePasswordResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      tags:
      - User
    get:
      description: Check to see if the user must obtain a Trust Token Id in order to complete a change password request. When a user has enabled Two-Factor authentication, before you are allowed to use the Change Password API to change your password, you must obtain a Trust Token by completing a Two-Factor Step-Up authentication.  An HTTP status code of 400 with a general error code of [TrustTokenRequired] indicates that a Trust Token is required to make a POST request to this API. OR Check to see if the user must obtain a Trust Token Id in order to complete a change password request. When a user has enabled Two-Factor authentication, before you are allowed to use the Change Password API to change your password, you must obtain a Trust Token by completing a Two-Factor Step-Up authentication.  An HTTP status code of 400 with a general error code of [TrustTokenRequired] indicates that a Trust Token is required to make a POST request to this API.
      operationId: retrieveUserChangePasswordWithId
      parameters:
      - name: ipAddress
        in: query
        schema:
          type: string
        description: IP address of the user changing their password. This is used for MFA risk assessment.
      - name: changePasswordId
        in: path
        schema:
          type: string
        required: true
        description: The change password Id used to find the user. This value is generated by FusionAuth once the change password workflow has been initiated.
      responses:
        '200':
          description: Success
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      tags:
      - User
  /api/user/comment:
    post:
      description: Adds a comment to the user's account.
      operationId: commentOnUserWithId
      parameters:
      - in: header
        name: X-FusionAuth-TenantId
        description: The unique Id of the tenant used to scope this API request. Only required when there is more than one tenant and the API key is not tenant-scoped.
        required: false
        schema:
          type: string
          format: UUID
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCommentRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserCommentResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      tags:
      - User
  /api/user/comment/search:
    post:
      description: Searches user comments with the specified criteria and pagination.
      operationId: searchUserCommentsWithId
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCommentSearchRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserCommentSearchResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      tags:
      - User
  /api/user/comment/{userId}:
    get:
      description: Retrieves all the comments for the user with the given Id.
      operationId: retrieveUserCommentsWithId
      parameters:
      - name: userId
        in: path
        schema:
          type: string
        required: true
        description: The Id of the user.
      - in: header
        name: X-FusionAuth-TenantId
        description: The unique Id of the tenant used to scope this API request. Only required when there is more than one tenant and the API key is not tenant-scoped.
        required: false
        schema:
          type: string
          format: UUID
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserCommentResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      tags:
      - User
  /api/user/consent:
    post:
      description: Creates a single User consent.
      operationId: createUserConsent
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserConsentRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserConsentResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      tags:
      - User
    get:
      description: Retrieves all the consents for a User.
      operationId: retrieveUserConsentsWithId
      parameters:
      - name: userId
        in: query
        schema:
          type: string
        description: The User's Id
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserConsentResponse'
        default:
          description: Error
      tags:
      - User
  /api/user/consent/{userConsentId}:
    post:
      description: Creates a single User consent.
      operationId: createUserConsentWithId
      parameters:
      - name: userConsentId
        in: path
        schema:
          type: string
        required: true
        description: The Id for the User consent. If not provided a secure random UUID will be generated.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserConsentRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserConsentResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      tags:
      - User
    patch:
      description: Updates, via PATCH, a single User consent by Id.
      operationId: patchUserConsentWithId
      parameters:
      - name: userConsentId
        in: path
        schema:
          type: string
        required: true
        description: The User Consent Id
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserConsentRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserConsentResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      tags:
      - User
    get:
      description: Retrieve a single User consent by Id.
      operationId: retrieveUserConsentWithId
      parameters:
      - name: userConsentId
        in: path
        schema:
          type: string
        required: true
        description: The User consent Id
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserConsentResponse'
        default:
          description: Error
      tags:
      - User
    delete:
      description: Revokes a single User consent by Id.
      operationId: revokeUserConsentWithId
      parameters:
      - name: userConsentId
        in: path
        schema:
          type: string
        required: true
        description: The User Consent Id
      responses:
        '200':
          description: Success
        default:
          description: Error
      tags:
      - User
    put:
      description: Updates a single User consent by Id.
      operationId: updateUserConsentWithId
      parameters:
      - name: userConsentId
        in: path
        schema:
          type: string
        required: true
        description: The User Consent Id
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserConsentRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserConsentResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      tags:
      - User
  /api/user/family:
    post:
      description: Creates a family with the user Id in the request as the owner and sole member of the family. You can optionally specify an Id for the family, if not provided one will be generated.
      operationId: createFamily
      parameters:
      - in: header
        name: X-FusionAuth-TenantId
        description: The unique Id of the tenant used to scope this API request. Only required when there is more than one tenant and the API key is not tenant-scoped.
        required: false
        schema:
          type: string
          format: UUID
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FamilyRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FamilyResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      tags:
      - User
    get:
      description: Retrieves all the families that a user belongs to.
      operationId: retrieveFamiliesWithId
      parameters:
      - name: userId
        in: query
        schema:
          type: string
        description: The User's id
      - in: header
        name: X-FusionAuth-TenantId
        description: The unique Id of the tenant used to scope this API request. Only required when there is more than one tenant and the API key is not tenant-scoped.
        required: false
        schema:
          type: string
          format: UUID
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FamilyResponse'
        default:
          description: Error
      tags:
      - User
  /api/user/family/pending:
    get:
      description: Retrieves all the children for the given parent email address.
      operationId: retrievePendingChildrenWithId
      parameters:
      - name: parentEmail
        in: query
        schema:
          type: string
        description: The email of the parent.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PendingResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      tags:
      - User
  /api/user/family/request:
    post:
      description: Sends out an email to a parent that they need to register and create a family or need to log in and add a child to their existing family.
      operationId: sendFamilyRequestEmailWithId
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FamilyEmailRequest'
      responses:
        '200':
          description: Success
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      tags:
      - User
  /api/user/family/{familyId}:
    put:
      description: Updates a family with a given Id. OR Adds a user to an existing family. The family Id must be specified.
      operationId: updateUserFamilyWithId
      parameters:
      - name: familyId
        in: path
        schema:
          type: string
        required: true
        description: The Id of the family to update.
      - in: header
        name: X-FusionAuth-TenantId
        description: The unique Id of the tenant used to scope this API request. Only required when there is more than one tenant and the API key is not tenant-scoped.
        required: false
        schema:
          type: string
          format: UUID
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FamilyRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FamilyResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      tags:
      - User
    post:
      description: Creates a family with the user Id in the request as the owner and sole member of the family. You can optionally specify an Id for the family, if not provided one will be generated.
      operationId: createFamilyWithId
      parameters:
      - name: familyId
        in: path
        schema:
          type: string
        required: true
        description: The Id for the family. If not provided a secure random UUID will be generated.
      - in: header
        name: X-FusionAuth-TenantId
        description: The unique Id of the tenant used to scope this API request. Only required when there is more than one tenant and the API key is not tenant-scoped.
        required: false
        schema:
          type: string
          format: UUID
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FamilyRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FamilyResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      tags:
      - User
    get:
      description: Retrieves all the members of a family by the unique Family Id.
      operationId: retrieveFamilyMembersByFamilyIdWithId
      parameters:
      - name: familyId
        in: path
        schema:
          type: string
        required: true
        description: The unique Id of the Family.
      - in: header
        name: X-FusionAuth-TenantId
        description: The unique Id of the tenant used to scope this API request. Only required when there is more than one tenant and the API key is not tenant-scoped.
        required: false
        schema:
          type: string
          format: UUID
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FamilyResponse'
        default:
          description: Error
      tags:
      - User
  /api/user/family/{familyId}/{userId}:
    delete:
      description: Removes a user from the family with the given Id.
      operationId: removeUserFromFamilyWithId
      parameters:
      - name: familyId
        in: path
        schema:
          type: string
        required: true
        description: The Id of the family to remove th

# --- truncated at 32 KB (92 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fusionauth/refs/heads/main/openapi/fusionauth-user-api-openapi.yml