{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","params":[],"results":{"codes":[]},"settings":""},"next":{"description":"","pages":[]},"title":"Users, Passwords, and the API","type":"basic","slug":"users-passwords-and-the-api","excerpt":"","body":"There are a number of API methods relating to user administration, including [Users](doc:users), [Authentication](doc:authentication-1), and [Change Password](doc:change-password). This document gives a brief overview of how these methods work to build user-facing applications.\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Creating a New User\"\n}\n[/block]\nTo create a new user using the API, submit a POST request that includes, at a minimum, `email` and `role_id`.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X POST \\\"[host]/rest/user\\\" -b cookies.txt -d '{\\\"email\\\":\\\"foo:::at:::bar.com\\\", \\\"role_id\\\":1}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nWhen you create the user, unless you are a [Super Users](doc:super-users), you cannot provide a `password` and the user is set as inactive (active=false). A `login_token` is assigned to the user, and sent to the user via email. The user must use this token to change their password using the change_password method. In a web application this token can be included in a URL the user clicks on to change their password.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Creating the New User's Password\"\n}\n[/block]\nOnce the user has their temporary `login_token`, they must create a password using the `change_password` method. This is accomplished in the API using either a PUT or a POST:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X PUT \\\"[host]/rest/change_password\\\" -d '{\\\"email\\\":\\\"[email protected]\\\",\\\"new_password\\\":\\\"123456\\\",\\\"login_token\\\":\\\"A2jdAWlD\\\"}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nThis request will reset the user's password and set the user to active (active=true). The user can now login.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Logging In\"\n}\n[/block]\nAny active User can login using the Authenticate method by POSTing either their `user_id` or `email`, along with their password:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X POST \\\"[host]/buzz/rest/authenticate\\\" -b cookies.txt -d '{\\\"email\\\":\\\"[email protected]\\\", \\\"password\\\":\\\"123456\\\"}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Lost Password\"\n}\n[/block]\nIf a User loses their password and wants to get a new `login_token` to change their password, they can POST to `change_password` without a `login_token` parameter:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X POST \\\"[host]/rest/change_password\\\" -d '{\\\"email\\\":\\\"[email protected]\\\"}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nThis will send the user an email that includes a new `login_token`, which can then be used by PUTting to `change_password`, as described above.\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Changing Password of Authenticated User\"\n}\n[/block]\nTo change the password of an authenticated User using their existing password, you make a PUT to the `authenticate` method including the existing password and the `new_password`. Note, this differs from the `change_password` method in that it does not accept a `login_token`.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X PUT \\\"[host]/rest/authenticate\\\" -d '{\\\"email\\\":\\\"[email protected]\\\",\\\"password\\\":\\\"123456\\\",\\\"new_password\\\":\\\"abcdef\\\"}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Technical Notes\"\n}\n[/block]\n* Buzz stores both the `password` field and `login_token` field as salted, hashed strings, never as cleartext. The only place these values appear in cleartext is in the emails sent to the user when a new token is requested.\n* Minimum password length can be set as an environment variable.","updates":[],"order":16,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"56cb853a245b841300806f82","parentDoc":null,"category":{"sync":{"isSync":false,"url":""},"pages":["56c7c193f9aa3b0d00c8458f","56cb80a4c675f50b00a4b826","56cb83859f4ae20b00644f1f","56cb853a245b841300806f82","56cb863c32011d2500681925","56cb88a4245b841300806f8b","56cb9915245b841300806fa7","56cb9a079f4ae20b00644f48","56cb9b5bc675f50b00a4b859","56cba5929f4ae20b00644f5d","56cba5c5d5c6241d00ef5e93","56cbab9c9f4ae20b00644f76","56cbad69c675f50b00a4b881","56cbb060d5c6241d00ef5ebb","56cf3c4d6c5d7a13005ee88c","56cf3d0e287eb20b009f9ec7","56cf3d7c5267d70b00494c42","56cf3ee0287eb20b009f9ecd"],"title":"Buzz Concepts","slug":"buzz-concepts","order":0,"from_sync":false,"reference":false,"_id":"56c7bab4606ee717003c4766","createdAt":"2016-02-20T01:00:36.607Z","project":"56c35c56c0c4630d004e864c","__v":18,"version":"56c35c56c0c4630d004e864f"},"githubsync":"","user":"56c39c05bc41330d009f25d7","version":{"version":"0.5","version_clean":"0.5.0","codename":"","is_stable":true,"is_beta":false,"is_hidden":false,"is_deprecated":false,"categories":["56c35c57c0c4630d004e8650","56c7b9e5379b311700ed8fe3","56c7bab4606ee717003c4766","56c7bb3613e5400d001e8cbd","56cf3f5a5267d70b00494c4b","56cf3f866c5d7a13005ee894","56fd3956caad892200847bce","599da256e7742b002588bb02"],"_id":"56c35c56c0c4630d004e864f","createdAt":"2016-02-16T17:28:54.864Z","project":"56c35c56c0c4630d004e864c","releaseDate":"2016-02-16T17:28:54.864Z","__v":8},"project":"56c35c56c0c4630d004e864c","__v":1,"createdAt":"2016-02-22T22:01:30.223Z"}

Users, Passwords, and the API


There are a number of API methods relating to user administration, including [Users](doc:users), [Authentication](doc:authentication-1), and [Change Password](doc:change-password). This document gives a brief overview of how these methods work to build user-facing applications. [block:api-header] { "type": "basic", "title": "Creating a New User" } [/block] To create a new user using the API, submit a POST request that includes, at a minimum, `email` and `role_id`. [block:code] { "codes": [ { "code": "curl -X POST \"[host]/rest/user\" -b cookies.txt -d '{\"email\":\"[email protected]\", \"role_id\":1}'", "language": "curl" } ] } [/block] When you create the user, unless you are a [Super Users](doc:super-users), you cannot provide a `password` and the user is set as inactive (active=false). A `login_token` is assigned to the user, and sent to the user via email. The user must use this token to change their password using the change_password method. In a web application this token can be included in a URL the user clicks on to change their password. [block:api-header] { "type": "basic", "title": "Creating the New User's Password" } [/block] Once the user has their temporary `login_token`, they must create a password using the `change_password` method. This is accomplished in the API using either a PUT or a POST: [block:code] { "codes": [ { "code": "curl -X PUT \"[host]/rest/change_password\" -d '{\"email\":\"[email protected]\",\"new_password\":\"123456\",\"login_token\":\"A2jdAWlD\"}'", "language": "curl" } ] } [/block] This request will reset the user's password and set the user to active (active=true). The user can now login. [block:api-header] { "type": "basic", "title": "Logging In" } [/block] Any active User can login using the Authenticate method by POSTing either their `user_id` or `email`, along with their password: [block:code] { "codes": [ { "code": "curl -X POST \"[host]/buzz/rest/authenticate\" -b cookies.txt -d '{\"email\":\"[email protected]\", \"password\":\"123456\"}'", "language": "curl" } ] } [/block] [block:api-header] { "type": "basic", "title": "Lost Password" } [/block] If a User loses their password and wants to get a new `login_token` to change their password, they can POST to `change_password` without a `login_token` parameter: [block:code] { "codes": [ { "code": "curl -X POST \"[host]/rest/change_password\" -d '{\"email\":\"[email protected]\"}'", "language": "curl" } ] } [/block] This will send the user an email that includes a new `login_token`, which can then be used by PUTting to `change_password`, as described above. [block:api-header] { "type": "basic", "title": "Changing Password of Authenticated User" } [/block] To change the password of an authenticated User using their existing password, you make a PUT to the `authenticate` method including the existing password and the `new_password`. Note, this differs from the `change_password` method in that it does not accept a `login_token`. [block:code] { "codes": [ { "code": "curl -X PUT \"[host]/rest/authenticate\" -d '{\"email\":\"[email protected]\",\"password\":\"123456\",\"new_password\":\"abcdef\"}'", "language": "curl" } ] } [/block] [block:api-header] { "type": "basic", "title": "Technical Notes" } [/block] * Buzz stores both the `password` field and `login_token` field as salted, hashed strings, never as cleartext. The only place these values appear in cleartext is in the emails sent to the user when a new token is requested. * Minimum password length can be set as an environment variable.