===== 2-Factor Authentication (2FA) =====

2-factor authentication in Lucy is based on [[https://authy.com|Authy]] service, which allows you to login to the system using a security token obtained via the mobile application or via SMS message. In order to set up 2FA for your Lucy, you will need to go through a few simple steps:

  - Obtain an API key
  - Configure Lucy to use the API key
  - Setup 2FA for all users


===== Obtain an API Key =====

You may either use our pre-configured API key or set up your own key. We **strongly** recommend to obtain your own API key for production setups, as using the pre-configured key will share your Lucy login information (emails, phone numbers and time of the login) with our Authy account. More than likely this is not what you need. **By default Lucy has no 2FA API key configured and doesn't send any login information outside.**


==== Use Pre-configured Key (NOT RECOMMENDED) ====

In order if you are running a test system and just want to check how 2FA works, you may use our test API key: ''ROnCZuDlRyPYa9Cys0L1q4x08hIIN06m'' (just copy it and proceed to "Configure Lucy" section below)


==== Generate Your Own Key ====

  * Create a new account on Twilio (free of charge): [[https://www.twilio.com/try-twilio]]
  * Open the console: [[https://console.twilio.com/]]
  * In the console go to Explore Products and find Authy:
  * 
    {{::authy_prod.png?600|}}
  * Press "Verify your phone number", enter your phone number to recieve a verification code,
then enter it to get your number validated.
{{ phone_number.png?600 }}
  * Set the application name (i.e. Lucy) in "Friendly name" column and hit "Create Application".
    {{ create_application.png?600 }}
  * Add your first user email and phone number.
    {{ first_user.png?600 }}
  * Select "App Token", then enter generated token number from "Authy" app on your phone.
{{ app_token.png?600 }} {{ token.png?600 }}
  *Choose your created application,
{{ application.png?600 }}
  * go to "Settings", press an eye icon at
"Production API KEY" and the system will show you your unique API key.
{{ api_key.png?600 }}
  *Copy this API key - you will need to paste it into Lucy

===== Configure Lucy =====

At this step, you should already have an API key. Open Lucy interface and go to "System" → "Advanced Settings" in the main menu and paste your API key into "2FA" field, then hit "Save".

{{ :2fa:2fa-4.png?600 }}

Now you're all set and can configure 2FA for your account.

===== Setup 2FA for user accounts =====

All users in the system should configure 2FA for them on their own (as it sends SMS to their phone). 

In order to do so, each user should:
  - Go to the "Account" page
  - Enter their phone in the corresponding fields
  - Hit "Save"
  - Press "Configure 2FA" and follow instructions on the screen

{{ :2fa:2fa-5.png?600 }}

A user will be logged out after configuring 2FA and the system will ask a 2FA token during the next login. 
In order to obtain a 2FA token, you may either use Authy mobile application or request a token via SMS.