Part 2 - User Authentication

In Part 1 of this guide, we learned how to create users for the lōm mobile application. In this part, we'll learn how those users can log in to the app and authenticate against the lōm API.

Main Screen

All authentication against Experience Endpoints is done using a token. Each token is specific to a user and grants access to any endpoint that you've specified in the endpoint configuration or the user group configuration.

The process of logging in is to simply check a user's email and password and return a token if they're valid. That token can then be used to request API endpoints on behalf of that user. Losant automatically authorizes a token against endpoints and will return a 401 (Unauthorized) error back to the client if the token doesn't allow access to an endpoint.

The first-time setup automatically creates a POST /auth route that we can use to get a user's token. Below is a screenshot of the workflow that is automatically generated.

Auth Workflow

The /auth requires the user's email and password to be sent as POST data. It then uses the Authenticate node to check if an Experience User has an identical email and password. If the authentication fails, a 401 (Unauthorized) is returned to the client. If the email and password are valid, the token and the user object, both of which are added to the payload by the Authenticate node, are returned to the client.

You can test this by requesting /auth using one of the Experience Users you created in Part 1.

curl -H "Content-Type: application/json" -X POST \
  -d '{"email":"test@example.com","password":"my-password"}' \
  https://example.onlosant.com/auth
{
  "token": "THE_USER_TOKEN",
  "user": { ... }
}

Now whenever a lōm user enters their email and password on the main screen, the client will POST them to /auth and obtain a token in order to make authenticated requests against the API.

Using the /auth route is the most common way users will authenticate against your API. For convenience, let's also modify the workflow we created in Part 1 to return a token whenever a user is registered. This removes the need to register the user and then make an additional API request to get the user's token.

Token Workflow

  1. Add a Generate Token node and insert it after the Create User node.
  2. Set the ID or Email Template to {{ data.body.email }}. The Generate Token node works by accepting the ID or email of an existing Experience User and then creates a token for that user.
  3. Set the Result Path to data.newUser.token.

As we saw above, the Authenticate node automatically creates a token, however you can use the Generate Token node to create a token whenever you want. This provides a way to implement custom authentication mechanisms if needed. With this, in addition to the POST /users endpoint, whenever a new user is registered, the client will be returned the new user object and its token as the result.

{
  "email": "test@example.com",
  "firstName": "Jane",
  "lastName": "Smith",
  ...
  "token": "THE_USER_TOKEN"
}

You can test endpoint authentication by using the /me route that is automatically generated by the first-time setup. First, get a token using the /auth route.

curl -H "Content-Type: application/json" -X POST \
  -d '{"email":"test@example.com","password":"my-password"}' \
  https://example.onlosant.com/auth
{
  "token": "THE_USER_TOKEN",
  "user": { ... }
}

You can use this token to request the authenticated GET /me route.

curl -H "Content-Type: application/json" \
  -H "Authorization: Bearer THE_USER_TOKEN" \
  https://example.onlosant.com/me
{ "user": { ... } }

Requesting authenticated routes is done by providing the token in one of three ways. The example above placed the token in the Authorization header. More details can be found on the endpoint documentation.

At this point, the lōm mobile app has everything it needs to successfully register users and allow those users to log in to the app. This concludes Part 2 of the application Experience walkthrough. The next part will describe how devices can be registered and associated with an Experience User.

Continue to Part 3: Device Registration