Request an embed token in your backend

To securely access an embedded Luzmo dashboard and/or the dashboard editor in your platform, you will first need to retrieve an embed authorization token granting temporary access to specific collections, dashboards or datasets. This request for an embed authorization token should occur in your backend (server-side code). Within this request, you can specify the necessary properties to ensure a multi-tenant setup of your embedded dashboards (all multi-tenant setups are discussed in this Academy article). Note the importance of specifying the role for your end-users when creating their embed tokens as well as the level of access for each resource: more information on that, below.

Server-side SDK's

We provide SDK's for different backend libraries and reduce the burden of having to code all the API calls yourself. All SDK's can be found here in our Developer documentation, and you can see the corresponding code examples by using the selectors on the top right of the Developer documentation page.

If we currently don't provide an SDK for your backend library, don't worry: Luzmo's API's all use REST calls with default HTTP verbs and JSON content, and so you should be able to write these calls yourself 😉

Embed Authorization request

In its simplest form (i.e. not providing any properties for a multitenant dashboard setup) you should specify:

1. The type of the authorization you want to create: "embed", in this case.
2. username: identifies the end-user uniquely and immutably. This should correspond to eg. the primary key for the end-user on your end. If it changes, the end-user will not have access to their previously created content anymore. So don't use eg. an e-mail address if those can change in your platform!
3. email, name: basic info on the end-user, to show eg. who is the dashboard author. The full name (i.e. first name and last name) is expected.
4. role: below, you can find the different roles. In the next section, a flow diagram will assist you in setting the right role for your user!
   • "viewer" - Embed users that should only be able to view and interact with one or more dashboards/variants/duplicates.
   • "designer" - embed users that should be able to create, edit, view and interact with one or more dashboards/variants/duplicates
   • "owner" - embed users that should be able to create, edit, view and interact with one or more dashboards/variants/duplicates, and next to that they should be able to favorite dashboard variants for other embed users within their suborganization.
5. (optionally, yet advised): The suborganization, which determines who can be seen and with whom one can share dashboards and datasets. If the suborganization is not specified it will be assigned the same value as the "username" property.
6. access: Your token should provide access to at least one resource. This property must specify the rights for each resource (i.e. what the embed user can do with the resources).
   • In the case of dashboards:
     • 'read' - gives the embed user the right to only view the dashboard.
     • 'use' - next to viewing a dashboard, the embed user is able to create a variant of the dashboard, or duplicate it (dashboard duplication is only supported in editMode “editFull”).
     • 'modify' - besides viewing, duplicating and creating a variant of the dashboard, the embed user can edit the dashboard itself.
     • 'own' besides viewing, duplicating, creating variants and editing the dashboard itself the user may favorite variants for other users and share and delete the dashboard.
   • In the case of datasets:
     • ’read' - users are only allowed to query the dataset in existing chart(s) that are accessible to them (i.e. the user is not able to use this dataset when creating/editing a dashboard).
     • 'use' - the user is also able to use this dataset when creating or editing a dashboard.
     • 'modify' - the user is able to use this dataset when creating or editing a dashboard, and is able to edit the dataset itself (e.g. change column names, create or alter hierarchies, create or alter derived columns, etc.).
     • 'own' besides being able to use and edit this dataset the user may share or delete the dataset.
   • In the case of collections, this will specify the list of Collections to which the token should have access to. The token will be given access to resources contained in the collection. The token gets access to securables inside the collection at the time of creation, so if a securable is added or removed from a collection the token will continue to have the original access. If a dashboard and/or dataset is specified in the token request, which is also accessible to the token through a Collection, the more specific right is applied (i.e the right specified in the dashboards / datasets property overrides the rights from the Collection).
     • When using a collection inheritRights must be specified to be either read, use, modify or own. These access rights will apply to all dashboards and datasets within the collection.

There is no limit on the number of tokens that you can request, so we recommend requesting an embed token each time the user performs an action in your platform that would require authorization (e.g. navigating to another embedded dashboard). This prevents end users running into errors because of tokens that expired due to inactivity!

Embed user role

To facilitate deciding which role you should specify in the authorization request for your user(s), we added below a small flow diagram!

Code example (Node.js)

const Luzmo = require('@luzmo/nodejs-sdk');
var client = new Luzmo({
    api_key: '< Your API key >',
    api_token: '< Your API token >'
  });

let promise = client.create('authorization', {
  type: 'embed',
  username: '12345678',
  suborganization: 'Burrito Co.',
  name: 'Embed user',
  email : 'embed_user@example.com',
	role: 'viewer',
  access: {
    collections: [
      {
        id: COLLECTION_ID,
        inheritRights: 'use'
      }
    ],
    dashboards: [
      {
        id: DASHBOARD_ID,
        rights: 'use'
      }
    ],
    datasets: [
      {
        id: DATASET_ID,
        rights: 'read'
      }
    ]		
  }
});

promise.then(function(result){
  // return result.id and result.token to the client
})

In case you are interested in toggling certain features (e.g. exporting, alerting, etc.) for your users, this Academy article will show you all feature flags which you can override on a user-level by specifying them in the embed authorization request!

As a result, you will receive a temporary embed authorization token from Luzmo. This is a JSON object with an id/token combination:

{ 
  "type": "embed",
  "id": "< the authorization key >",
  "token": "< the authorization token >",
  "user_id": "< the embed user id >," // This will stay the same for consecutive embed authorization requests, 
                                    // and it is used on our end to manage user-specific content such as alerts
  ...
}

The second step is to use this token to embed the dashboard(s) in your frontend and optionally add dashboard designing possibilities, which is explained in our next article.