# Management

# 2FA

Currently, we support TOTP and WebAuthn as Two-factor Authentication methods. Enforcing users to use one of these is a great way to ensure that extra bit of security for your users.

# Disable Globally Enforcing 2FA

POST /api/v1/settings/usermanagement/globally_enforce_2fa/disable

Do not force users to use 2FA when logging into your Console.

Required Parameters

auth_token string
A valid auth token

Response

JSON structure with result indicator.

Example

    Response
    {
      "result": "success"
    }
    
    1
    2
    3

    # Enable Globally Enforcing 2FA

    POST /api/v1/settings/usermanagement/globally_enforce_2fa/enable

    Force users to use 2FA when logging into your Console.

    Required Parameters

    auth_token string
    A valid auth token

    Response

    JSON structure with result indicator.

    Example

      Response
      {
        "result": "success"
      }
      
      1
      2
      3

      # Add User

      POST /api/v1/user/add

      Add a new user to your Console.

      Required Parameters

      auth_token string
      A valid auth token
      email string
      The email address of the user to be added
      access_level string
      The user access level of the user. Either 'admin' or 'user'

      Optional Parameters

      totp_enabled boolean
      Whether to enable two-factor authentication for this user or not
      note string
      A text string for storing information related to the user
      send_welcome_mail boolean
      Defaults to: true
      Whether to send the user an email with the login link or not

      Response

      JSON structure with result indicator.

      Example

        Response
        {
          "msg": "User (<user_email>) successfully created.",
          "result": "success"
        }
        
        1
        2
        3
        4

        # Add User Note

        POST /api/v1/user/note/add

        Add a note to a user.

        Required Parameters

        auth_token string
        A valid auth token
        email string
        The email address of the user
        note string
        A text string for storing information related to the user

        Response

        JSON structure with result indicator.

        Example

          Response
          {
            "msg": "User (<user_email>) note successfully added.",
            "result": "success"
          }
          
          1
          2
          3
          4

          # Assign User to Flocks

          POST /api/v1/user/flock/assign

          Assign a user to one or more flocks.

          Required Parameters

          auth_token string
          A valid auth token
          email string
          The email address of the user
          flock_id_list string
          A comma separated list of the flocks the user should be assigned (1 or more)
          flock_access_level string
          The type of privileges the user should have (Either 'manager' or 'watcher')

          Response

          JSON structure with result indicator.

          Example

            Response
            {
              "msg":"User <user_email> successfully assigned to watcher flock(s) [u'flock:default', u'<flock_id>']",
              "result":"success"
            }
            
            1
            2
            3
            4

            # Disable User

            POST /api/v1/user/disable

            Disables a specified user. This user will not be able to login.

            Required Parameters

            auth_token string
            A valid auth token
            email string
            The email address of the user to be disabled

            Response

            Example

              Response
              {
                "msg": "User (<user_email>) successfully disabled.",
                "result": "success"
              }
              
              1
              2
              3
              4

              # Disable User's TOTP

              TIP

              This is useful for when a user loses access to their Two Factor authentication app (for example losing their phone) and cannot log in to the Console. Temporarily disabling their TOTP will allow them to log back into the Console and reset it.

              POST /api/v1/user/2fa/disable

              Disables TOTP for a specified user.

              Required Parameters

              auth_token string
              A valid auth token
              email string
              The email address of the user

              Response

              JSON structure with result indicator.

              Example

                Response
                {
                  "msg": "Successfully disabled two-factor authentication for user <user_email>",
                  "result": "success"
                }
                
                1
                2
                3
                4

                # Disable User's WebAuthn

                TIP

                This is useful for when a user loses access to their WebAuthn authenticator (for example losing their YubiKey) and cannot log in to the Console. Temporarily disabling their WebAuthn will allow them to log back into the Console and reset it.

                POST /api/v1/user/webauthn/disable

                Disable WebAuthn for a specified user.

                Required Parameters

                auth_token string
                A valid auth token
                email string
                The email address of the user to be removed

                Response

                JSON structure with result indicator.

                Example

                  Response
                  {
                    "result": "success"
                  }
                  
                  1
                  2
                  3

                  # Edit User

                  POST /api/v1/user/edit

                  Edits a specified user.

                  Required Parameters

                  auth_token string
                  A valid auth token
                  email string
                  The email address of the user to be edited

                  Optional Parameters

                  note string
                  A text string for storing information related to the user

                  Response

                  Example

                    Response
                    {
                      "msg": "User (<user_email>) successfully edited.",
                      "result": "success"
                    }
                    
                    1
                    2
                    3
                    4

                    # Edit User Access Level

                    POST /api/v1/user/edit/access_level

                    Edits a user's access level.

                    Required Parameters

                    auth_token string
                    A valid auth token
                    email string
                    The email address of the user to be edited
                    access_level string
                    Access level to change to (Either 'admin' or 'user')

                    Response

                    JSON structure with result indicator.

                    Example

                      Response
                      {
                        "result": "success"
                      }
                      
                      1
                      2
                      3

                      # Enable User

                      POST /api/v1/user/enable

                      Enables a specified user. This user will be able to login if previously disabled.

                      Required Parameters

                      auth_token string
                      A valid auth token
                      email string
                      The email address of the user to be enabled

                      Response

                      JSON structure with result indicator.

                      Example

                        Response
                        {
                          "msg": "User (<user_email>) successfully enabled.",
                          "result": "success"
                        }
                        
                        1
                        2
                        3
                        4

                        # Remove User

                        POST /api/v1/user/remove

                        Remove a user from the Console.

                        Required Parameters

                        auth_token string
                        A valid auth token
                        email string
                        The email address of the user to be removed

                        Response

                        JSON structure with result indicator.

                        Example

                          Response
                          {
                            "msg": "User (<user_email>) successfully removed.",
                            "result": "success"
                          }
                          
                          1
                          2
                          3
                          4

                          # Remove User from Flocks

                          POST /api/v1/user/flock/unassign

                          Remove a user to one or more flocks.

                          Required Parameters

                          auth_token string
                          A valid auth token
                          email string
                          The email address of the user
                          flock_id_list string
                          A comma separated list of the flocks the user should be removed from (1 or more)
                          flock_access_level string
                          The type of privileges the user should have (Either 'manager' or 'watcher')

                          Response

                          JSON structure with result indicator.

                          Example

                            Response
                            {
                              "msg": "User <user_email> successfully unassigned from manager flock(s) [u'flock:default', u'<flock_id>']",
                              "result": "success"
                            }
                            
                            1
                            2
                            3
                            4

                            # Remove User Note

                            DELETE /api/v1/user/note/delete

                            Remove a user's note.

                            Required Parameters

                            auth_token string
                            A valid auth token
                            email string
                            The email address of the user

                            Response

                            JSON structure with result indicator.

                            Example

                              Response
                              {
                                "msg": "User (<user_email>) note successfully removed.",
                                "result": "success"
                              }
                              
                              1
                              2
                              3
                              4

                              # Reset User Password

                              TIP

                              When resetting a user's password, they'll receive a "Password Reset" email.

                              POST /api/v1/user/password/reset

                              Reset a user's password.

                              Required Parameters

                              auth_token string
                              A valid auth token
                              email string
                              The email address of the user whose password will be reset

                              Response

                              JSON structure with result indicator.

                              Example

                                Response
                                {
                                  "msg": "Password reset email sent to <user_email>",
                                  "result": "success"
                                }
                                
                                1
                                2
                                3
                                4