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

self-hosted in-browser custom

  // Create a token that is used for dashboard access.
  const dashboardAccessToken = await vizzlySigner.signDashboardAccessToken({
    // Is the user a standard user, or should they have 'admin'
    // access allowing them to manage the dashboard for ALL your users.
    accessType: 'standard',

    // What is your organisation ID? Find yours by running the CLI command
    // `vizzly current-profile`
    // or on the https://app.vizzly.co/dashboards page.
    organisationId: '<< Your organisation ID >>',

    // A unique identifier for the current user, that you are
    // happy for Vizzly to store.
    userReference: '<< A reference to the current user >>',

    // Either `read` or `read_write`
    scope: 'read_write',
  });

See the full file

Create the data access token

self-hosted

  // Create a token that is used for data access in a multi-tenant environment.
  const dataAccessToken = await vizzlySigner.signDataAccessToken({
    // 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-hosted

This token grants access to members of your engineering team to use the Config Manager.

  // Generate an access token for the Vizzly Config Manager UI
  // https://docs.vizzly.co/query-engines/self-hosted/config-manager-ui
  const queryEngineAccessToken = await vizzlySigner.signQueryEngineAccessToken({
    // Allow the user access to the database schema. This is required if you want the
    // user to access the Vizzly Config Manager UI.
    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;

Setting up the Dashboard React component
Setting up the self-hosted Vizzly Query Engine

Signing a Vizzly Config

If you are dynamically generating and sending a Vizzly Config to the Vizzly Query Engine, you can use the signVizzlyConfig function to sign the config ready to send it in the config header.

Identity and Multi-Tenancy Python client