Integration Helper: Generating a JWT Session Token

The PeerBoard Community Integration Helper: Generating a JWT Session Token Mikhail Larionov

We use JWT tokens to pass user session information to PeerBoard from your custom built website. There're two main ways to do that:

When embedding PeerBoard in an iframe through our SDK and using JWT to automatically authenticate your users. Read more.
By having PeerBoard to live somewhere else outside of your product and creating a link in your product that would automatically log this user in PeerBoard. Read more.

Respective guides above give more color on each path, this specific guide explains how to generate a JWT token on your backend to use in either scenario.

Implementation

We will use javascript in an example below, but you can implement it in any programming language. You can find the JWT library for your programming language at jwt.io

Save your PeerBoard API Auth Token at a secure location on your backend server. You can find the token at your community Settings -> Hosting.

const apiAuthToken = "<API AUTH TOKEN>";

Install the JWT library of your choice.

npm install jsonwebtoken

Get the user data from the session or your database.

const createPeerBoardAuthToken = (request, response) => {
  const user = await getUserById(request.auth.user_id);

Create a token payload.

❗️ Important: Data from payload used only to create user, after that we don't update these fields from the token payload, if you want to sync the profiles with your application consider to use our API.

const payload = {
  creds: {
    v: 'v1',
    fields: {
      // We highly recommend to provide unique user id from you system
      // to be keep things in sync in the future
      // Email is a bad identifier(it may change). Should be a string.
      // Optional.
      external_id: user.id,

      // Required. Used to send notifications and digests.
      email: user.email,

      // Optional. If empty, the user will be asked to enter her name.
      name: user.username,

      // Optional. You can also specify the last name.
      last_name: user.last_name,

      // Image URL for the avatar - should be publicly available
      // so that our backend can download it.
      // Optional.
      avatar_url: user.image, 

      // Optional user bio that we will show in her profile.
      bio: user.bio,

      // Optional string to show near user name.
      tagline: user.tagline,

      // Optional external member profile url
      // This will replace PeerBoard profiles everywhere in
      // the community.
      //
      // DEPRECATION: Would no longer skip member onboarding.
      // Use skip_onboarding if you want this behaviour.
      profile_url: user.profile_url,

      // Skip PeerBoard onboarding screen.
      skip_onboarding: false,

      // Optionally you can prove a role.
      // By default it will be "member" on user creation
      // We recommend to set a correct role to the user at that point, 
      // so the admin users and moderators from 
      // your application could access admin panel.
      role: "ADMIN"|"MEMBER"|"MODERATOR",

      // Optional list of groups to add the user, consider
      // implementing more tight sync with our API if you
      // want to sync removing from group
      add_to_groups: [ { id: 12324 }, { external_id: "hd63v8a96" } ]
    }
  }
};

We recommend to restrict the lifetime of the token, but give it enough time so if a user stays on your page, the link will still work after a while.

const jwtOpts = {
  expiresIn: 3600 // seconds
};

Sign the token using the library and send it to the frontend.

const token = jsonwebtoken.sign(payload, apiAuthToken, jwtOpts);

response.send(token);

💡 Note You can debug your token with the debugger on jwt.io. It should look like this.

This is it, refer to the two guides mentioned at the beginning of the page to put the token to use!