{"_id":"56cb853a245b841300806f82","parentDoc":null,"category":{"_id":"56c7bab4606ee717003c4766","project":"56c35c56c0c4630d004e864c","__v":18,"pages":["56c7c193f9aa3b0d00c8458f","56cb80a4c675f50b00a4b826","56cb83859f4ae20b00644f1f","56cb853a245b841300806f82","56cb863c32011d2500681925","56cb88a4245b841300806f8b","56cb9915245b841300806fa7","56cb9a079f4ae20b00644f48","56cb9b5bc675f50b00a4b859","56cba5929f4ae20b00644f5d","56cba5c5d5c6241d00ef5e93","56cbab9c9f4ae20b00644f76","56cbad69c675f50b00a4b881","56cbb060d5c6241d00ef5ebb","56cf3c4d6c5d7a13005ee88c","56cf3d0e287eb20b009f9ec7","56cf3d7c5267d70b00494c42","56cf3ee0287eb20b009f9ecd"],"version":"56c35c56c0c4630d004e864f","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-02-20T01:00:36.607Z","from_sync":false,"order":0,"slug":"buzz-concepts","title":"Buzz Concepts"},"githubsync":"","user":"56c39c05bc41330d009f25d7","version":{"_id":"56c35c56c0c4630d004e864f","project":"56c35c56c0c4630d004e864c","__v":8,"createdAt":"2016-02-16T17:28:54.864Z","releaseDate":"2016-02-16T17:28:54.864Z","categories":["56c35c57c0c4630d004e8650","56c7b9e5379b311700ed8fe3","56c7bab4606ee717003c4766","56c7bb3613e5400d001e8cbd","56cf3f5a5267d70b00494c4b","56cf3f866c5d7a13005ee894","56fd3956caad892200847bce","599da256e7742b002588bb02"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"0.5.0","version":"0.5"},"project":"56c35c56c0c4630d004e864c","__v":1,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-02-22T22:01:30.223Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":10,"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\\\":\\\"foo@bar.com\\\",\\\"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\\\":\\\"foo@bar.com\\\", \\\"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\\\":\\\"foo@bar.com\\\"}'\",\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\\\":\\\"foo@bar.com\\\",\\\"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.","excerpt":"","slug":"users-passwords-and-the-api","type":"basic","title":"Users, Passwords, and the API"}

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\":\"foo@bar.com\", \"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\":\"foo@bar.com\",\"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\":\"foo@bar.com\", \"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\":\"foo@bar.com\"}'", "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\":\"foo@bar.com\",\"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.