Looking for Dashboard < 0.12.0, or the Query Engine < v0.10.0?
Identity and Multi-Tenancy
Node client

NodeJs

This guide takes you through using the Vizzly Auth Package (opens in a new tab) to sign the identity config securely on your servers.

If you are looking for more information about each of the properties, you can find that here.

Install

npm install @vizzly/auth

Import

import * as VizzlyAuth from '@vizzly/auth';

Create the signer

  const vizzlySigner = VizzlyAuth.createSigner({ ttlInMinutes, privateKey });
See the full file

To load your private key from an environment variable, you can see the guide here.

Create the dashboard access token

  const dashboardAccessToken = await vizzlySigner.signDashboardAccessToken({
    /*  [REQUIRED]
        What is the ID of your project?
        You can find this on the project details page. It will start with `prj_`
    */
    projectId: '<< Your project ID >>',

    /* [REQUIRED]
       A unique identifier for the current user, that you are
       happy for Vizzly to store.
    */

    userReference: '<< A reference to the current user >>'

    /* [OPTIONAL]
       Control 'admin' mode for the parent dashboard.
       This is an advanced feature, and should only be used
       to allow members of your organisation access to the
       parent dashboard.

       Default: 'standard'
    */
    //  accessType: 'standard' | 'admin'

    /* [OPTIONAL]
       Prevent the user from making any changes to their dashboard.

       Default: 'read_write'
    */
    //  scope: 'read' | 'read_write'

    /* [OPTIONAL]
       List the parent dashboard IDs the user has access too.

       Default: undefined
    */
    //  parentDashboardIds: Array<string>;
  });
See the full file

Create the data access token

  const dataAccessToken = await vizzlySigner.signDataAccessToken({
    /*
      What is the ID of your project?
      You can find this on the project details page. It will start with `prj_`
    */
    projectId: '<< Your project ID >>',

    /*
      What data sets does this user have access too?
      If can either be a list of data set IDs, or a "*" to allow
      access to all data sets.
    */
    dataSetIds: ['hr-payroll-data', 'hr-people-data'],

    /*
      What secure filters need to be added, to ensure this user
      only sees their own data? For example here, we set a filter
      to only use data where the field `field_user_id` equals a
      specific user ID.
    */

    secureFilters: {
      'hr-payroll-data': [
        {
          field: 'field_user_id',
          op: '=',
          value: "<< the user's ID >>"
        }
      ],
      'hr-people-data': [
        {
          field: 'field_user_id',
          op: '=',
          value: "<< the user's ID >>"
        }
      ]
    },

    /* [OPTIONAL]
      Provide an object of key/values that
      can be used in the Vizzly Query Engine's
      SQL backed data sets feature.
    */
    parameters: {}
  });
See the full file

Create the query engine access token (optional)

OptionalSelf-hostedAdvanced

This is an advanced option for accessing the Query Engine from the embedded dashboard. Generally, you should access the Query Engine via its "Sign In" page.

  const queryEngineAccessToken = await vizzlySigner.signQueryEngineAccessToken({
    // What is the ID of your project?
    // You can find this on the project details page. It will start with `prj_`
    projectId: '<< Your project ID >>',

    // Allow the user access to the database schema. This is required if you want the
    // user to access the Vizzly Config Manager.
    allowDatabaseSchemaAccess: true,

    // Allow the user to fetch 'preview' data from the database when
    // configuring the datasets for the Vizzly Query Engine.
    allowDataPreviewAccess: true
  });
See the full file

Next steps

Now that you have created the access tokens, you will want to return the access tokens to the client. For example, you might be calling this auth endpoint from the identity function used on the Dashboard. If that's the case, then you'll want to return the tokens in a JSON structure of this format;

{
  /** Required */
  dashboardAccessToken: string;
  /** Required if you are using the self-hosted Vizzly query engine */
  dataAccessToken?: string;
  /** Optional if the user has access to the config manager */
  queryEngineAccessToken?: string;
}

Now that you are finished generating access tokens for Vizzly, you might be interested in;