{"_id":"5bb2813d1da2590003732a29","project":"569f9cf6650e1d1900f96b5b","version":{"_id":"569f9cf6650e1d1900f96b5e","project":"569f9cf6650e1d1900f96b5b","__v":12,"createdAt":"2016-01-20T14:43:02.785Z","releaseDate":"2016-01-20T14:43:02.785Z","categories":["569f9cf7650e1d1900f96b5f","56abdd81d4432d1900eed235","56abe0558beeff0d003b8118","56ad2f8b1c09150d00a183a8","56ad4e1cd21f1b0d00fd2f97","56b00ad88f7a4f0d0029dc92","56b2432e9621f20d00efb2bd","56b25826147e900d00d6497a","56b7af2a4b372d2100722c48","56b8c4d938b1070d0028920f","56b8cdab14feef0d0082415d","58599813cf9e112d0032cdab"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"category":{"_id":"56b25826147e900d00d6497a","project":"569f9cf6650e1d1900f96b5b","version":"569f9cf6650e1d1900f96b5e","pages":["56b2583a9621f20d00efb31c","56b25a3965ddf50d0076baa2","56b2738894ab060d0006743c","56b4d1cf5f1cf00d00cc46d7","56b4f4e2b1a8690d00a59369","56b4f6925f1cf00d00cc4704","56b4fa3d5997532100bc6bcc","56b50ba8eed075230097d71e","56b5123585a6922300d1c506","56b51e475997532100bc6c08","56b5220b7719bb1900143055","56b524cc3d5f130d00dad1b8","56b5265b168b5c1700c15996","56b774438fb4420d006a618b","56b78012eb783a0d007894f3","56b78292a6c10c0d00a2d65d","56b7863aeb783a0d007894f8","56b78f68a6c10c0d00a2d66b","56b794566c2a240d0094ae8a","56b7a85dd22adc0d0053f4c2","56b7ac118fb4420d006a61b7"],"__v":21,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-02-03T19:42:30.051Z","from_sync":false,"order":7,"slug":"user-methods","title":"User methods"},"user":"5ae8c2a466355e0003269bc6","__v":0,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2018-10-01T20:19:09.848Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":999,"body":"\"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.\n\nEach 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.\n\nAn 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.\n\nExisting 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.\n\n## Syntax \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    <credentials object>, \\n    \\\"user\\\": <mailbox_name>, \\n    \\\"mode\\\": <string>, \\n    \\\"tag\\\": <string>\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Request fields for app_password\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field name\",\n    \"h-1\": \"Obligation\",\n    \"h-2\": \"Definition/Value\",\n    \"0-0\": \"user\",\n    \"0-1\": \"Required\",\n    \"0-2\": \"the user the API call is acting upon\",\n    \"1-0\": \"mode\",\n    \"1-1\": \"Required\",\n    \"1-2\": \"a string, either \\\"add\\\" or \\\"remove\\\"\",\n    \"2-0\": \"tag\",\n    \"2-1\": \"Optional / Required if mode==\\\"remove\\\"\",\n    \"2-2\": \"a string.\\n\\nfor \\\"add\\\", the tag name desired for this new App Password. tags are constrained to regular ASCII characters only.\\n\\nfor \\\"remove\\\", the tag name of the App Password to remove.\"\n  },\n  \"cols\": 3,\n  \"rows\": 3\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Response fields for app_password\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"error\",\n    \"0-1\": \"Returned if **success = false**\",\n    \"0-2\": \"A text string that explains the error.\",\n    \"1-0\": \"error_number\",\n    \"1-1\": \"Returned if **success = false**\",\n    \"1-2\": \"A number that represents the error.\",\n    \"2-0\": \"success\",\n    \"2-1\": \"Always returned.\",\n    \"2-2\": \"Indicates whether the request was successful or not. Allowed values are **true** and **false**.\",\n    \"3-0\": \"password\",\n    \"3-1\": \"Returned if mode==\\\"add\\\"\",\n    \"3-2\": \"The value of the newly generated App Password\"\n  },\n  \"cols\": 3,\n  \"rows\": 4\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Examples for app_password\"\n}\n[/block]\n**Request 1**\n\nAdd an App Password to a user.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"credentials\\\": {\\n\\\"user\\\": \\\"company_admin:::at:::resellerusername.adm\\\",\\n    \\\"password\\\": \\\"password\\\"\\n  },\\n  \\\"user\\\": \\\"user@customerdomain1.com\\\",\\n  \\\"mode\\\": \\\"add\\\",\\n  \\\"tag\\\": \\\"my phone\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n**Response 1**\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n\\t\\\"success\\\": true,\\n  \\\"password\\\": \\\"UF3W-5PFC-KJDJ-62SK\\\",\\n\\t\\\"audit\\\": \\\"month72_56b3b161b\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n**Request 2**\n\nRemove an App Password from a user.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"credentials\\\": {\\n\\\"user\\\": \\\"company_admin@resellerusername.adm\\\",\\n    \\\"password\\\": \\\"password\\\"\\n  },\\n  \\\"user\\\": \\\"user@customerdomain1.com\\\",\\n  \\\"mode\\\": \\\"remove\\\",\\n  \\\"tag\\\": \\\"my phone\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n**Response 2**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n\\t\\\"success\\\": true,\\n\\t\\\"audit\\\": \\\"month72_56b3b161b\\\"\\n}\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]","excerpt":"Adds or removes \"App Passwords\" for the given end user.","slug":"app_password","type":"basic","title":"app_password"}

Introduction

Authentication Methods

Company methods

Domain methods

Workgroup methods

User methods

Brand Methods

Stats methods

Migration methods

app_password

Adds or removes "App Passwords" for the given end user.
"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 [block:code] { "codes": [ { "code": "{\n <credentials object>, \n \"user\": <mailbox_name>, \n \"mode\": <string>, \n \"tag\": <string>\n}", "language": "json" } ] } [/block] [block:api-header] { "title": "Request fields for app_password" } [/block] [block:parameters] { "data": { "h-0": "Field name", "h-1": "Obligation", "h-2": "Definition/Value", "0-0": "user", "0-1": "Required", "0-2": "the user the API call is acting upon", "1-0": "mode", "1-1": "Required", "1-2": "a string, either \"add\" or \"remove\"", "2-0": "tag", "2-1": "Optional / Required if mode==\"remove\"", "2-2": "a string.\n\nfor \"add\", the tag name desired for this new App Password. tags are constrained to regular ASCII characters only.\n\nfor \"remove\", the tag name of the App Password to remove." }, "cols": 3, "rows": 3 } [/block] [block:api-header] { "title": "Response fields for app_password" } [/block] [block:parameters] { "data": { "0-0": "error", "0-1": "Returned if **success = false**", "0-2": "A text string that explains the error.", "1-0": "error_number", "1-1": "Returned if **success = false**", "1-2": "A number that represents the error.", "2-0": "success", "2-1": "Always returned.", "2-2": "Indicates whether the request was successful or not. Allowed values are **true** and **false**.", "3-0": "password", "3-1": "Returned if mode==\"add\"", "3-2": "The value of the newly generated App Password" }, "cols": 3, "rows": 4 } [/block] [block:api-header] { "title": "Examples for app_password" } [/block] **Request 1** Add an App Password to a user. [block:code] { "codes": [ { "code": "{\n \"credentials\": {\n\"user\": \"company_admin@resellerusername.adm\",\n \"password\": \"password\"\n },\n \"user\": \"user@customerdomain1.com\",\n \"mode\": \"add\",\n \"tag\": \"my phone\"\n}", "language": "json" } ] } [/block] **Response 1** [block:code] { "codes": [ { "code": "{\n\t\"success\": true,\n \"password\": \"UF3W-5PFC-KJDJ-62SK\",\n\t\"audit\": \"month72_56b3b161b\"\n}", "language": "json" } ] } [/block] **Request 2** Remove an App Password from a user. [block:code] { "codes": [ { "code": "{\n \"credentials\": {\n\"user\": \"company_admin@resellerusername.adm\",\n \"password\": \"password\"\n },\n \"user\": \"user@customerdomain1.com\",\n \"mode\": \"remove\",\n \"tag\": \"my phone\"\n}", "language": "json" } ] } [/block] **Response 2** [block:code] { "codes": [ { "code": "{\n\t\"success\": true,\n\t\"audit\": \"month72_56b3b161b\"\n}", "language": "text" } ] } [/block]