Users, Passwords, and the API

There are a number of API methods relating to user administration, including Users, Authentication, and Change Password. This document gives a brief overview of how these methods work to build user-facing applications.

Creating a New User

To create a new user using the API, submit a POST request that includes, at a minimum, email and role_id.

curl -X POST "[host]/rest/user" -b cookies.txt -d '{"email":"foo@bar.com", "role_id":1}'

When you create the user 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.

Creating the New User's Password

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:

curl -X PUT "[host]/rest/change_password" -d '{"email":"foo@bar.com","new_password":"123456","login_token":"A2jdAWlD"}'

This request will reset the user's password and set the user to active (active=true). The user can now login.

Logging In

Any active User can login using the Authenticate method by POSTing either their user_id or email, along with their password:

curl -X POST "[host]/buzz/rest/authenticate" -b cookies.txt -d '{"email":"foo@bar.com", "password":"123456"}'

Lost Password

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:

curl -X POST "[host]/rest/change_password" -d '{"email":"foo@bar.com"}'

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.

Changing Password of Authenticated User

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.

curl -X PUT "[host]/rest/authenticate" -d '{"email":"foo@bar.com","password":"123456","new_password":"abcdef"}'

Technical Notes

• 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.