why deepstreamHub? compare us getting started feature roadmap faq
use cases pricing
products
developers
company
blog contact

Session tokens are becoming increasingly popular and they are extremely easy to set up with deepstream.

Just follow this guide along and you'll have session tokens ready for your application in just a few minutes.

This guide will use a Javascript Client.

Create a free account and get your API key

By default, email authentication is disabled in a deepstream application, you can access and edit which types of authentication your users can login with via the Auth page.

However, if you try and add users in your application, you'll automatically be prompted to enable email authentication first.

Here's how it should look like, on your dashboard:

email-auth

The idea of using session tokens is simple. Once you log into deepstream via email, deepstream issues a token. This particular token is only valid for a period of 24hrs. However, within these 24hrs, you can use just this token to repeatedly login into deepstream without having to enter you email and password every time.

Let's understand this better with an example.

Connect to deepstream

As mentioned earlier, we will make use of a JS client library. Include it in your application as follows:

<script src="https://code.deepstreamhub.com/js/latest/deepstream.min.js"></script>

In your script, connect to deepstream as follows:

// Connect to deepstreamHub
const client = deepstream('<YOUR APP URL')

Using a session token for logging in

For this example, we will use localStorage to store our token. To login, first check if a token exists in the localStorage. If it does, attempt a login with the existing token to check if it is still valid (i.e it was generated within 24hrs). If it does not exist, it means you are logging in for the first time - in which case, you will need to login using your email and password. This is illustrated below:

//retrieve a token from the localStorage
const token = localStorage.getItem('deepstream-token')
//if it is not null,
if (token) {
  //token exists but not validated yet
  //attempt to resume the previous session using this token
  resumeSession(token)
} else {
  //token does not exist
  //logging in for the first time
  loginWithEmail()
}

Now consider that a token exists, however, we are not yet sure if it is valid. Let's check for it's validity and if it fails, we'll ask the user to login via email auth as shown below:

function resumeSession (token) {
  //try logging in with session token
  client.login({
      token: token
  }, function(success, data) {
    if (success) {
        onSuccessfulLogin(data)
    } else {
      //login failed means the token has expired
      loginWithEmail()
    }
 })
}

However, if the token is valid, we call the onSuccessfulLogin function and send the data as an argument and continue with the main functionality of the application.

Whenever we make the client login with an email and password, we need to make sure to replace the token in the localStorage by the newly generated one which is returned by the server, as shown below:

function loginWithEmail () {
  //ask the client to enter his credentials
  const myEmail = prompt("Enter email", "");
  const myPass = prompt("Enter your passwords", "");
  //login with email auth
  client.login({
      email: myEmail,
      password: myPass
  }, function(success, data) {
      if (success) {
          //replace the token in localStorage with new one
          localStorage.setItem('deepstream-token', data.token)
          onSuccessfulLogin(data)
      } else {
        // user login failed
      }
  })
}

The last thing is to handle any other operations you wish to do once the user is authenticated, as shown below:

function onSuccessfulLogin (data) {
  console.log("logged in")
  // navigate to main page
  //or handle other operations
}

You're all set with using sessions tokens for authentication on deepstream. Simple as that !