Generate an Embed Authorization token

The first step to provide embedded resources in your application is to ensure you can securely authorize your application's end-users to access specific Luzmo resources & features, while also making sure they can only access the data they should have access to (e.g. multi-tenancy ). To do so, you should use an API key-token pair of an Organization Owner and use that server-side to request short-living Embed Authorization tokens. The result of this request is an Embed key-token pair that can be used to securely access specific Luzmo content client-side: Embedded dashboards or the dashboard editor, Flex widgets, or even Luzmo IQ.

The API request is a 'create' request for an Authorization resource. In the snippet below, fill in your API key & token, add the user's details and the resources (collections, dashboards and or datasets) you want to give access to.

import Luzmo from '@luzmo/nodejs-sdk';
const client = new Luzmo({
  api_key: '<your Luzmo API key>',
  api_token: '<your Luzmo API token>',
  host: 'https://api.luzmo.com'
});


const response = await client.create('authorization',
  {
    type: "embed",
    username: "<A unique and immutable identifier for your user>",
    name: "<username>",
    email: "<user_email>",
    suborganization: "<a suborganization name>",
    access: {
      collections: [
        {
          id: "<collection_id>",
          inheritRights: "use"
        }
      ],
      datasets: [
        {
          id: "<dataset_id>",
          rights: "use"
        }
      ],
      dashboards: [
        {
          id: "<dashboard_id>",
          rights: "use"
        }
      ]
    }
  }
);

Below you can find an initial list of properties you can specify here:

This returns a JSON object with an id/token combination that you can use to securely embed Luzmo content in your application/platform:

{
  "type": "embed",
  "id": "< the embed authorization key >",
  "token": "< the embed authorization token >",
  "user_id": "< a uuid used on Luzmo's end to identify the embed user >"
  // ...
}

Handling multi-tenant data

Multi-tenancy is the ability of software to serve multiple clients. This means that depending on the client that logs into your platform, the embedded Luzmo content will only contain their relevant data .

There are multiple ways to implement this and Luzmo aims to provide a good solution for each of them. Setting up secure multi-tenancy in Luzmo happens via the Embed tokens and their properties.

Which specific properties are used depends on your data structure. Depending on your current data setup and use case, it might be necessary to dynamically:

• apply dynamic row-level filtering using Parameterized filters , in case you have one dataset with multi-tenant data

• point towards a different data source in case you have one dataset per tenant using Connection overrides

More in-depth information about these features and how to implement them in Luzmo can be found in the Handling multi-tenant data section .

Allowing or denying access to a set of Luzmo features

For each Authorization token, you can specify a list of Feature flags that ensure your end-user can only perform a specific set of actions with that Embed token. This allows you to control which end-users can use e.g. the Exporting feature, configure Alerts, add datasets, etc.

In this Create Authorization request, we're specifying feature_overrides to deny the use of the Exporting and Alerting feature, but allow the user to connect their own Bigquery data source in the embedded dashboard editor

import Luzmo from '@luzmo/nodejs-sdk';
const client = new Luzmo({
  api_key: '<your Luzmo API key>',
  api_token: '<your Luzmo API token>',
  host: 'https://api.luzmo.com'
});


const response = await client.create('authorization',
  {
    type: "embed",
    username: "<A unique and immutable identifier for your user>",
    name: "<username>",
    email: "<user_email>",
    suborganization: "<a suborganization name>",
    access: {
      collections: [
        {
          id: "<collection_id>",
          inheritRights: "use"
        }
      ]
    },
    feature_overrides: ["!flag_alerting", "!flag_exporting", "flag_bigquery"]
  }
);

Prematurely invalidating Embed tokens

Embed Authorization tokens have an expiry (default when not specified: 24 hours from creation) and inactivity_interval (defaults to 0 when not specified) property that ensure any Embed token will expire at a given moment in time: you can control these properties when generating an Embed Authorization token .

If necessary, you can invalidate an Embed token prematurely using a "Delete" action on the Authorization API endpoint ; note that it can only be invalidated by using the Embed key-token itself to sign the request.

import Luzmo from '@luzmo/nodejs-sdk';
const client = new Luzmo({
  api_key: '<Embed authorization id>',
  api_token: '<Embed authorization token>',
  host: 'https://api.luzmo.com'
});

await client.delete('authorization', '<the authorization id>');