Users, Passwords, and the API

There are a number of API methods relating to user administration, including /users, /authenticate, and /change-password. This document gives a brief overview of how these methods work to build user-facing applications. See also Authentication.

Creating a New User

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

curl -X POST "[host]/rest/v2/user" 
  -b cookies.txt 
  -d '{"email":"[email protected]", "first_name":"Queen","last_name":"Bee","role_id":1}'
  -H "Content-Type: application/json"

When you create the user you cannot provide a password and the user is set as inactive (active=false). In the UI workflow an email is sent to the user and they are asked to set a password. Once the user's password is reset the user is set to active (active=true) and can now login.

Logging In

Any active User can login using the Authenticate method by POSTing their email, along with their password. See Authentication for a full explanation with examples.

Lost Password

If a User loses their password and wants to get an email to change their password, they can POST to request-change-password:

curl -X POST "[host]/rest/v2/request-change-password" 
  -b cookies.txt 
  -d '{"email":"[email protected]"}'
  -H "Content-Type: application/json"

This will send the user an email that links to a webpage where they can update their password.

Changing Password of Authenticated User

To change the password of an authenticated User using their existing password, you make a POST to the change_password resource including the existing password and the new_password.

curl -X POST "[host]/rest/v2/change-password" 
  -b cookies.txt 
  -d '{"password":"123456","new_password":"abcdef"}'
  -H "Content-Type: application/json"