Create Authorization

Authorizations are key-token pairs that grant access to the Luzmo platform and/or Luzmo resources. The most common use-case is to create an API key-token pair in our UI, and use that in your application to create short-living Embed Authorization key-token pairs via our API. Embed tokens can be used for your application's users to access specific Luzmo datasets and embedded dashboards.

Types of Authorization tokens

There are 3 types of tokens that you can create programmatically and/or manually:

1. Login tokens
   These tokens are created when you manually authenticate to the platform. Via the API you will only come into contact with them when you create a new user programmatically. The response of creating a new user via API will contain a login key-token pair; this login token can be used to create an Authorization token of type api .

   • Programmatic: the only way to create a new login token is to create a new user .

   • Manual: authenticate (log in) to the platform.

2. API tokens
   API tokens can be used to programmatically perform API actions on Luzmo resources (e.g. creating Embed Authorization tokens, updating entities, pushing new data points, etc.).

   • Programmatic: use an active Login Authorization token to create an Authorization token of type api .

   • Manual: in your Luzmo profile, you can create new API key-token pairs, as well as see your existing API keys. You can also invalidate them in this page, similar to deleting an Authorization token via API.

3. Embed tokens
   Embed Authorizations can be used to temporarily delegate access to one or more datasets and dashboards to e.g. an end-user within your own platform. They can only be created with an active API Authorization key-token pair from an Organization owner user.
   Embed tokens can have access restrictions to limit which securables can be accessed (via Collections, as well as directly to one or more dashboards and/or datasets), which data filters are automatically applied to all queries, ...
   Embed tokens are implicitly associated with a bootstrapped Luzmo user based on the username property in the "create" request. Luzmo will use this to manage user-generated content and track Monthly Active Views (MAVs) & Designers (MADs).

   • Programmatic: use an active API Authorization token from an "Organization owner" user to create an Authorization token of type embed .

   • Manual: you cannot create embed tokens via the UI.

Tokens can be created in a cascaded way as described above ("login" → "api" → "embed"), but are always ultimately tied to a single User. In case of a Login or API Authorization, that is the user that initially created the Authorization token. In case of an Authorization token with type embed , the token is implicitly associated with its bootstrapped User (see above).

Access rights for Embed tokens

Authorization tokens of type embed are typically used to provide users in your platform access to one or more Luzmo securables (i.e. datasets and/or dashboards). Such access is most commonly provided via the access property in the Authorization request, but can also be achieved by associating a Securable with the bootstrapped User or (suborganization) Group. The following rules apply to access rights ( read , use , modify , own ) to dashboards and/or datasets:

• Access provided within the access property of the Authorization request:

  • Within Collections via the collections property: the highest level of inherited access is given to a securable amongst all Collections, in case that securable is accessible through multiple Collections.

    • E.g. If two collections both provide inherited access to a securable, but one provides access rights "use" while the other provides "modify" access rights, the token will inherit "modify" access for that securable.

  • In case a securable is accessible through both a Collection and directly via the datasets or dashboards property, the direct access rights will override the inherited access rights.

    • E.g. If the token has inherited "use" access to a dataset via a Collection, but receives "modify" access to the same dataset via the datasets property, the token will have "modify" access to that dataset.

• Only the highest access rights given via the access property (see previous bullet point), and through its bootstrapped User and any Group(s) they are a member of, will be taken into account.

  • E.g.:

    • If the token's access property specifies "use" access to a dataset, but the token's bootstrapped User has received "modify" access to that dataset, the token will effectively have "modify" access.

    • If a user's group has "modify" access to a dashboard while the user itself has "use" access to that dashboard, the embed token will effectively have "modify" access to that dashboard due to its group having such access.

For embed tokens, the simplest access management to dashboards and datasets happens via Collections and the collections array inside the access property of the Authorization request. This way you can easily manage access rights for a token to multiple securables at once. If you need to provide/override access rights to specific securables (e.g. customer-specific dashboards that are not in a Collection), you can do so via the datasets or dashboards property of the Authorization request.

Merging of data filters for Embed tokens

When an Authorization token of type embed queries a dataset (e.g. via an embedded dashboard), filters from different origins will be applied. The following three sets of filters are merged together using "AND" relations when Embed tokens query a dataset:

• Filters that are always applied:

  • Filters specified via the filters property of Authorization token.

  • All interactivity filters from dashboard items (e.g. selection in a column chart, date range selection, etc.).

• Filters that are always applied, unless it's a parameterized filter that is cleared via the parameter_overrides property in the Authorization request:

  • Embed filters on datasets are always applied, unless parameterized and explicitly cleared.

  • Dashboard & chart filters are always applied, unless parameterized and explicitly cleared.

• Filters that are applied in the following priority (if the user has access to a dataset via User and/or Group access ): User-specific filters (if available), then Group filters (if user-specific filters are not set), and finally Public group filters (if neither user-specific nor group filters are set). E.g.:

  • If filter(s) are specified on an associated group that the user is part of, as well as on the direct association to the user itself, only the filter(s) specified on the user's association will be applied.

  • If filter(s) are specified on multiple associated groups of which the user is member of, and no filters are specified on the user's access itself, the filter(s) of the different group-securable associations will be merged together using "AND" relations.

Below you can find the specific properties that can be set when creating an Authorization token.