Enabling two-factor also impacts Mail User/Alias API auth

[JJJ]

Problem

Enabling two-factor auth changes how accounts authenticate into the Mail User & Alias APIs.

This means if you have a script or custom service that currently authenticates with single factor (password) that you later setup two-factor on (password & one-time-password) those scripts/services will stop working – rightfully so!

This behavior isn't made perfectly clear – and is perhaps unintentionally misdirected – thanks to this message (emphasis mine):

When two-factor authentication is enabled, you will be prompted to enter a six digit code from an authenticator app (usually on your phone) when you log into this control panel.

"this control panel" unintentionally implied to me to mean the web GUI, without making mention of the command-line API's.

Possible Solution(s)

Verbiage change:

When two-factor authentication is enabled, you will be prompted to enter a six digit code from an authenticator app when you log into this control panel and required to include it as a header with API requests.

API usage

In order to authenticate via the command-line with two-factor enabled, we must pass the x-auth-token value in as a header, and curl allows this via a --header flag.

Perhaps we can amend the (advanced) section to include that in the Usage: examples.

The email and password given to the --user option must be an administrative user on this system.

When two-factor authentication is enabled, add --header "x-auth-token: 123456" where 123456 is the six digit code from your authenticator app.

[JoshData]

Makes sense!