### How regular user / password log in works in Humand
This is the simplest form of user authentication in Humand.
The user enters their username in a login form, then it is presented with a list of communities to which they can login and the user has to select one, and 
finally enter the password in the login form, and the system validates the credentials against the database.

Sequence diagram of the log in flow:
```mermaid
sequenceDiagram
    participant U as User
    participant H as Humand
    U->>+H: Access Humand app (or admin or mobile)
    H-->>-U: Render login form prompting for username

    U->>+H: POST /api/v1/auth/instances { employeeInternalId }
    H-->>-U: HTTP 200 (OK) [{"id": 1348, "name": "Humand"}, ...]

    U->>+H: POST /api/v1/auth/login { instanceId, employeeInternalId, password }
    H-->>-U: HTTP 200 (OK) { "instance": {...}, "user": {...}, "tokens": {...} }
```

### How OTP log in works in Humand
This workflow only relies on using a one-time password (OTP) to authenticate the user.
The user enters their username in a login form, then it is presented with a list of communities to which they can login and the user has to select one. 
Because the instance is configured with `forceOTP: true`, the user is asked to confirme his phone number and then the OTP is sent to the user's phone as an 
SMS message. 
Finally, the user enters the received OTP in the form, and the system validates it and generates the JWT and returns it to the user.

Sequence diagram of the log in flow:
```mermaid
sequenceDiagram
    participant U as User
    participant H as Humand
    participant SMS as SMS Gateway
    U->>+H: Access Humand app (or admin or mobile)
    H-->>-U: Render login form prompting for username

    U->>+H: GET /api/v1/auth/instances { employeeInternalId }
    H-->>-U: HTTP 200 (OK) [{"id": 1348, "name": "Humand"}, ...]

    U->>+H: GET /api/v1/auth/otp { instanceId, employeeInternalId }
    H-->>-U: HTTP 200 (OK) [{ "id": 1348, "name": "Humand", "forceOTP": true }, ...]

    U->>+H: POST /api/v1/auth/otp/send { instanceId, employeeInternalId, channel }
    H->>+SMS: Send OTP to phone number
    SMS->>-H: HTTP 200 (OK)
    H-->>-U: HTTP 204 (NO CONTENT)
    
    SMS->>U: SMS message including OTP code

    U->>+H: POST /api/v1/auth/otp/login { instanceId, employeeInternalId, channel, code }
    H->>+SMS: Verify OTP code
    SMS->>-H: HTTP 200 (OK)
    H-->>-U: HTTP 200 (OK) { "instance": {...}, "user": {...}, "tokens": {...} }
```

### How user / password + OTP log in works in Humand
This form of user authentication in Humand combines the two other methods explained before.
The user enters their username in a login form, then it is presented with a list of communities to which they can login and the user has to select one, and
finally enter the password in the login form, and the system validates the credentials against the database. If correct, it returns a code to the client
so that the frontend can render the OTP flow, asking for confirmation about their phone number and sending the OTP to the user's phone as an SMS message.
Finally, the user enters the received OTP in the form, and the system validates it and generates the JWT and returns it to the user.

Sequence diagram of the log in flow:
```mermaid
sequenceDiagram
    participant U as User
    participant H as Humand
    U->>+H: Access Humand app (or admin or mobile)
    H-->>-U: Render login form prompting for username

    U->>+H: POST /api/v1/auth/instances { employeeInternalId }
    H-->>-U: HTTP 200 (OK) [{"id": 1348, "name": "Humand", "otpAfterRegularLogin": true}, ...]

    U->>+H: POST /api/v1/auth/otp/init-2fa { instanceId, employeeInternalId, password }

    Note right of H: Instead of JWT, the response includes an init2faToken<br> that needs to be sent back later with the OTP<br>See details below.
    H-->>-U: HTTP 200 (OK) { "init2faToken": "abcedf" }

    U->>+H: POST /api/v1/auth/otp/send { instanceId, employeeInternalId, channel }
    H->>+SMS: Send OTP to phone number
    SMS->>-H: HTTP 200 (OK)
    H-->>-U: HTTP 204 (NO CONTENT)

    SMS->>U: SMS message including OTP code

    U->>+H: POST /api/v1/auth/otp/login { instanceId, employeeInternalId, channel, code, init2faToken: "abcedf" }
    Note left of H: Include the token received in the init 2fa step
    H->>+SMS: Verify OTP code
    SMS->>-H: HTTP 200 (OK)
    H-->>-U: HTTP 200 (OK) { "instance": {...}, "user": {...}, "tokens": {...} }
```