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.

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({
    // 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 >>',

    // A unique identifier for the current user, that you are
    // happy for Vizzly to store.
    userReference: '<< A reference to the current user >>'
  });
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 >>"
        }
      ]
    }
  });
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;