The built-in User model represents an application end-user.

All of the endpoints in the table below are inherited from PersistedModel REST API, except for the following:

Quick reference

URI Pattern HTTP Verb Default Permission Description Arguments
/users POST Allow

Add user instance and persist to data source. Inherited from PersistedModel API.

JSON object (in request body) providing User object properties: username, password, email. LoopBack sets values for emailVerified and verificationToken.

NOTE: A value for username is not required, but a value for email is. LoopBack validates a unique value for password is provided. LoopBack does not automatically maintain values of the created and lastUpdated properties; you can set them manually if you wish.
/users GET Deny Find matching instances of users that match specified filter. Inherited from PersistedModel API.

One or more filters in query parameters:

  • where
  • include
  • order
  • limit
  • skip / offset
  • fields
/users PUT Deny Update / insert user instance and persist to data source. Inherited from PersistedModel API.

JSON object (in request body)

Same as for POST /users
/users/id GET Deny Find user by ID: Return data for the specified user ID. Inherited from PersistedModel API. id, the user ID (in URI path)
/users/id PUT Deny Update user attributes for specified user ID and persist. Inherited from PersistedModel API.

Query parameters:

  • data An object containing property name/value pairs
  • id The model id
/users/id DELETE Deny Delete user with specified instance ID. Inherited from PersistedModel API. id, user ID (in URI path)
/users/id/accessTokens GET Deny Returns access token for specified user ID.
  • id, user ID, in URI path
  • where in query parameters
/users/id/accessTokens POST Deny Create access token for specified user ID.

id, user ID, in URI path
/users/id/accessTokens DELETE Deny Delete access token for specified user ID.

id, user ID, in URI path
/users/confirm GET Deny Confirm email address for specified user.

Query parameters:

  • uid
  • token
  • redirect
/users/count GET Deny

Return number of user instances that match specified where clause. Inherited from PersistedModel API.

"Where" filter specified in query parameter
/users/id/exists GET Deny

Check instance existence: Return true if specified user ID exists. Inherited from PersistedModel API.

URI path:

  • users - Model name
  • id - Model instance ID
/users/findOne GET Deny

Find first user instance that matches specified filter. Inherited from PersistedModel API.

One or more filters in query parameters:

  • where
  • include
  • order
  • limit
  • skip / offset
  • fields
/users/login[?include=user]

POST

 Allow

Log in the specified user.

Username and password in POST body.

If query parameter is include=user, then returns the user object.
/users/logout POST Allow Log out the specified user. Access token in POST body.
/users/reset POST   Reset password for the specified user. In POST body

Log in user

POST /users/login

You must provide a username or an email, and the password in the request body. To ensure these values are encrypted, include these as part of the body and make sure you are serving your app over HTTPS (through a proxy or using the HTTPS node server).

You may also specify how long you would like the access token to be valid by providing a ttl (time to live) property with value in seconds. 

Example

Request URL: POST  http://localhost:3000/users/login

Request body:

{
    "email": "foo@bar.com",
    "password": "bar",
    "ttl": 86400
  }

Response status code: 200

Response body:

{
  "id": "PqosmmPCdQgwerDYwQcVCxMakGQV0BSUwG4iGVLvD3XUYZRQky1cmG8ocmzsVpEE",
  "ttl": 86400,
  "created": "2014-12-23T08:31:33.464Z",
  "userId": 1
}

The access token for the user’s session is returned in the id key of the response. It must be specified in the query parameter access_token for all the APIs that requires the user to be logged in. For example:

http://localhost:3000/api/Users/logout?access_token=PqosmmPCdQgwerDYwQcVCxMakGQV0BSUwG4iGVLvD3XUYZRQky1cmG8ocmzsVpEE.

Log out user

POST /users/logout

Example

Request URL: POST  http://localhost:3000/api/Users/logout?access_token=PqosmmPCdQgwerDYwQcVCxMakGQV0BSUwG4iGVLvD3XUYZRQky1cmG8ocmzsVpEE.

Response status code: 204

Confirm email address

Require a user to verify their email address before being able to login. This will send an email to the user containing a link to verify their address. Once the user follows the link they will be redirected to web root (“/”) and will be able to login normally.

GET /users/confirm

Parameters

Query parameters:

  • uid
  • token
  • redirect

Return value

If token invalid: HTTP 400

If user not found: HTTP 404

If successful: HTTP 204

Reset password

POST /users/reset

Parameters

POST payload:

{
  "email": "foo@bar.com"
  ...
}

Return value

200 OK

You must the handle the ‘resetPasswordRequest' event to send a reset email containing an access token to the correct user.

The example below shows how to get an access token that a user can use to reset their password. 

common/models/user.js

User.on('resetPasswordRequest', function (info) {
  console.log(info.email); // the email of the requested user
  console.log(info.accessToken.id); // the temp access token to allow password reset

  // requires AccessToken.belongsTo(User)
  info.accessToken.user(function (err, user) {
    console.log(user); // the actual user
  });
});

See also Verifying email addresses (Registering users).

Tags: models