app_password

"App Passwords" are used in lieu of an account's regular password when authenticating to services that cannot support Two-Factor Authentication (POP3, IMAP4, SMTP, CalDAV, CardDAV). Once one has been set on a user account, their password will be unable to authenticate against those services; they must use one of the App Passwords instead.

Each App Password has a tag (name) associated with it. Multiple devices/clients may use the same App Password, or they may be configured to each use a different one. Up to 4 App Passwords may be configured.

An App Password may be removed at any time (in the case of a lost device); the other App Passwords will continue to function. If the final App Password is removed, then the user's password will once again work to authenticate with non-2FA services.

Existing App Password tags are returned in the get_user response. Once an App Password is set, there is no way to retrieve the value of the password associated with it, only the tag.

Syntax

{
    <credentials object>, 
    "user": <mailbox_name>, 
    "mode": <string>, 
    "tag": <string>
}

Request fields for app_password

Field name	Obligation	Definition/Value
user	Required	the user the API call is acting upon
mode	Required	a string, either "add" or "remove"
tag	Optional / Required if mode=="remove"	a string. for "add", the tag name desired for this new App Password. tags are constrained to regular ASCII characters only. for "remove", the tag name of the App Password to remove.

Field name

Obligation

Definition/Value

user

Required

the user the API call is acting upon

mode

Required

a string, either "add" or "remove"

tag

Optional / Required if mode=="remove"

a string.

for "add", the tag name desired for this new App Password. tags are constrained to regular ASCII characters only.

for "remove", the tag name of the App Password to remove.

Response fields for app_password


error	Returned if success = false	A text string that explains the error.
error_number	Returned if success = false	A number that represents the error.
success	Always returned.	Indicates whether the request was successful or not. Allowed values are true and false.
password	Returned if mode=="add"	The value of the newly generated App Password

Examples for app_password

Request 1

Add an App Password to a user.

{
  "credentials": {
"user": "[email protected]",
    "password": "password"
  },
  "user": "[email protected]",
  "mode": "add",
  "tag": "my phone"
}

Response 1

{
	"success": true,
  "password": "UF3W-5PFC-KJDJ-62SK",
	"audit": "month72_56b3b161b"
}

Request 2

Remove an App Password from a user.

{
  "credentials": {
"user": "[email protected]",
    "password": "password"
  },
  "user": "[email protected]",
  "mode": "remove",
  "tag": "my phone"
}

Response 2

{
	"success": true,
	"audit": "month72_56b3b161b"
}