---
title: Create Authorization
url: https://developer.luzmo.com/api/createAuthorization
type: api
resource: authorization
action: create
method: POST
---

# 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](/api/createUser.md).
   * *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](/api/deleteAuthorization.md) 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](api/associateCollection.md) 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](/api/associateEmbedFilterGroup.md) 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](/api/associateDataset.md)): 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.

## Endpoint

- **Method**: `POST` (all Luzmo API calls use POST with an action parameter)
- **Path**: `/authorization`
- **Action**: `create`
- **Base URL**: `https://api.luzmo.com` (EU), `https://api.us.luzmo.com` (US), or your VPC-specific API Host URL

## Request Parameters

### Available Parameters

- **type** (required): `"embed" | "api" | "login" | "sso"` - Type of Authorization token to create. Possible types created by an API token are:
  - `embed`: create a temporary embed token for an end-user.
  - *`sso`: (deprecated in favor of **type `embed`**) create a temporary single sign-on token for an end-user.*

  Other token types:
  - `login`: a token created when manually authenticating using your user credentials
  - `api`: API token for programmatic access to Luzmo resources. Can be created only through a `login` token
- **access** (required): `object` - Specifies which datasets and dashboards the token should have access to, either through one or more Collections or directly to the specified datasets and/or dashboards. You must provide access to at least one resource.
  - In the introduction paragraph on top (under **"Access rights for Embed tokens"**), you can find more information about how access rights are applied when a Securable is accessible via multiple resources.
  - Don't forget to also provide access to each dashboards' underlying dataset(s) to avoid 'No access' errors!
  - **collections**: `array<object>` - List of Collections that contain one or more securables (dashboards and/or datasets), to which the token should have access to. Note that the token will not have access to the Collection itself, but rather uses the Collection to access the underlying resources.
    * If a securable is added or removed from a collection, you must generate a new token (i.e the token gets access to securables inside the collection at the time of creation).
    * If you specify a securable in the dashboards / datasets property which is also accessible through a Collection that includes this dashboard / dataset, the more specific right is applied (i.e the right specified in the dashboards / datasets property overrides the inherited right via the Collection).
    - **id**: `string (uuid)` - ID of the collection through which you'd like to provide access to its underlying securables (i.e. dashboards & datasets).
    - **inheritRights**: `"read" | "use" | "modify" | "own"` - The access rights the token should have to the dashboard(s) and/or dataset(s) inside the specified collection.
      Note that the API token used to generate the embed token must have equal or higher access to the securables in the collection! If not, a warning message will be returned in the response to indicate that the embed token doesn't have access to one or more of the collection's securables.

      Provides the following access to the securables inside the collection:
      * `read`:
      * dashboards: Can only view and interact with the dashboard and its items.
      * datasets: Can only query the dataset in the context of an existing dashboard item.
      * `use`:
      * dashboards: Can view and interact with the dashboard, as well as duplicate it or create variants in the embedded editor.
      * datasets: Can query the dataset freely (within the embed token's context). This is the minimal access required to be able to use the dataset in the embedded editor or in Luzmo Flex.
      * `modify`:
      * dashboards: Can view, interact, and modify this dashboard.
      * datasets: Can modify the dataset, e.g. creating new columns, changing column types, etc.
      * `own`:
      * dashboards: Can view, interact, modify, share, and delete the dashboard.
      * datasets: Can share and delete the dataset.
  - **datasets**: `array<object>` - List of datasets the token should have access to, with their individual access rights. If dataset(s) are specified which are also accessible through a specified Collection, the explicit dataset access rights specified here will override the inherited access right from the Collection.
    - **id**: `string (uuid)` - Id of the dataset to which your token should have access to
    - **rights**: `"read" | "use" | "modify" | "own"` - The access the embed token should have to the specified dataset. Note that the API token used to generate the embed token must have equal or higher access to the dataset!

      Provides the following access to the dataset:
      * `read`: Can only query the dataset in the context of an existing dashboard item.
      * `use`: Can query the dataset freely (within the embed token's context). This is the minimal access required to be able to use the dataset in the embedded editor or in Luzmo Flex.
      * `modify`: Can modify the dataset, e.g. creating new columns, changing column types, etc.
      * `own`: Can share and delete the dataset.
  - **dashboards**: `array<object>` - List of dashboards the token should have access to, with their individual access rights. If dashboard(s) are specified which are also accessible through a specified Collection, the explicit dashboard access rights specified here will override the inherited access right from the Collection.
    - **id**: `string (uuid)` - ID of the dashboard to which your token should have access to
    - **rights**: `"read" | "use" | "modify" | "own"` - The access the embed token should have to the specified dashboard. Note that the API token used to generate the embed token must have equal or higher access to the dashboard!

      Provides the following access to the dashboard:
      * `read`: Can only view and interact with the dashboard and its items.
      * `use`: Can view and interact with the dashboard, as well as duplicate it or create variants in the embedded editor.
      * `modify`: Can view, interact, and modify this dashboard.
      * `own`: Can view, interact, modify, share, and delete the dashboard.
- **username** (required): `string` - Viewer metadata: The username of the end-user. Identifies the user uniquely and immutably.
  This should correspond to eg. the primary key for the user on your end. If it changes, the user will not have access to their previously created content anymore. Don't use e.g. an e-mail address if those can change in your platform!

  This will be used to uniquely identify a Monthly Active Viewer (MAV) or Monthly Active Designer (MAD) for your Organization. If not used in a fair manner, functional session cookies will be used to distinguish monthly active users.

  Please note that the only special characters that are allowed in the username are: `.` `&` `_` `-` `+` `@` `'` `(` `)` and `!`.
- **name** (required): `string` - Viewer metadata: name of the end-user. This will be used in the Luzmo UI (e.g. in the tour in the embedded editor).
  Note that only the following special characters are allowed: `.` `&` `_` `-` `+` `@` `'` `(` `)` and `!`.
- **email** (required): `string (email)` - Viewer metadata: email address of the end-user. This will be used in the Luzmo UI (e.g. prefilled into the Alert Email channel modal).
  Note that this must be a valid email address format, e.g. `example@domain.com`.
- **suborganization**: `string` - Each embed token should be in a suborganization. The suborganization determines which other users they can see & interact with. it defaults to username to have total isolation, set to null if you want all users to see each other.
  - Default: `"<username>"`
- **role**: `"designer" | "owner" | "viewer"` - The role of the user for who you are making the authorization request. This will influence which actions Luzmo will allow or deny (e.g. a "viewer" role is not allowed to switch to edit mode).

  - `viewer`: only able to view and interact with one or more dashboards or variants.

  - `designer`: able to view, interact, **edit, and create** one or more dashboards, variants, and duplicates.

  - `owner`: able to view, interact, edit, and create one or more dashboards, variants, and duplicates. Next to that, "owner" tokens can **favorite** dashboard variants for other embed users within their suborganization.
  - Default: `"viewer"`
- **expiry**: `string (date-time)` - RFC3339 timestamp when this authorization will cease working. Defaults to 24 hours from creation default, with a maximum of 1 year.

  This is the hard (maximum) expiry time of the token, after which it will **always** be invalid. We advise using short expiry time, eg. 24 hours from now.

  Upon expiry of the token, the [authorizationExpired](guide/embedding--component-api-reference.md) event will be emitted.
  - Default: `"< 24 hours from creation >"`
- **inactivity_interval**: `integer` - Duration of inactivity (in seconds) after which the token is **prematurely invalidated**. Defaults to `0`.
  You can use this to prematurely invalidate tokens when the user session in your application has ended (eg. all open dashboards are closed).

  A value of `0` means no premature invalidation due to inactivity (the token will only expire on the datetime specified in the `expiry` property of the Authorization request).
  For non-zero values the minimum is 120 seconds, this is to avoid accidental invalidation for a dashboard that is still open, eg. when a heartbeat signal sent to the server is missed.

  Upon expiry of the token, the [authorizationExpired](guide/embedding--component-api-reference.md) event will be emitted.
  - Default: `"0"`
- **parameter_overrides**: `object` - Use this property to override parameter values of a parameterized filter(s). This must be a valid JSON object with a maximum length of 200k characters. This is commonly used for multi-tenancy filtering, see [here](/guide/dashboard-embedding--handling-multi-tenant-data.md). See intro on top (under **"Merging of data filters for Embed tokens"**) for more information about filtering behaviour when Embed tokens query data.
  * To clear parameterized filter(s) completely (i.e. not apply them), override its value to: `{"< parameter name >": {"clear": true}}`
  * To mark sensitive parameters that should not be logged, like JWT or authentication tokens, store it as an object with the sensitive property set: `{"< parameter name >": {"sensitive": true, "value": "..."}}`
  * To mark a parameter as sticky to make sure its value is always used in future scheduled exports and alerts created by this token, rather than an updated value from a newer token for the same username, set: `{"< parameter name >": {"sticky": true, "value": "..."}}}`

  This property is only available for Authorization of type 'embed', for Authorization tokens with deprecated type 'sso', you should use the metadata property.
- **account_overrides**: `object` - Used to dynamically override one or more data connections (to a Plugin or database, see differences below). You can use this to dynamically route data requests (e.g. to a [single-tenant database](/guide/dashboard-embedding--handling-multi-tenant-data.md), schema, tables, etc.). All overrides are optional -- if not specified, the value as configured on the original Connection will be used instead.

  Please check the [Create Authorization examples](/api/createAuthorization/examples/create-an-embed-token/js) to see which Connection overrides your data source connection requires.
  - **< plugin_connection_id >**: `object` - The Connection ID for the Plugin connection for which you want to override properties.
    - **base_url**: `string` - The new plugin base URL that will be called. Must be a valid HTTPS URL that does not end with `\`.
    - **properties**: `object` - The custom authentication properties to override for plugin-based connections. You can optionally override one or more custom authentication properties that were defined when setting up the plugin in Luzmo.
      These will be sent as `X-Property-< custom_property_id >` headers to the Plugin.
      - **< custom_property_identifier >**: `string` - The new custom authentication property value. The key is the custom authentication property id as defined when setting up the plugin in Luzmo.
    - **datasets**: `object` - List of dataset-level overrides. Useful if you e.g. have a separate table per client, and want to dynamically point one or more Luzmo datasets to their respective client-specific table.
      - **< dataset_id >**: `object` - The Luzmo dataset (securable) ID that you want to override.
        - **table**: `string` - The new canonical dataset identifier (as defined by the Plugin) to retrieve data from.
  - **< database_connection_id >**: `object` - The database connection id for which you want to override properties as property name.
    - **host**: `string` - The new database host to connect to. The database must be of the same type as the originally configured database (i.e. you cannot override a MySQL connection to a PostgreSQL connection).
    - **port**: `string` - The new port to connect to.
    - **database**: `string` - The new database to retrieve data from.
      Note that to MySQL the concepts database and schema are identical. So when overriding a database / schema for MySQL, make sure to pass the same value to both schema and database
    - **schema**: `string` - The new schema to retrieve data from.
      Note that to MySQL the concepts database and schema are identical. So when overriding a database / schema for MySQL, make sure to pass the same value to both schema and database
    - **user**: `string` - The new user to use when connecting.
    - **password**: `string` - The new password to use when connecting.
    - **datasets**: `object` - List of dataset-level overrides. Useful if you e.g. have a separate table per client, and want to dynamically point one or more Luzmo datasets to their respective client-specific table.
      The SQL query of the dataset can also be overridden if it's a SQL dataset within Luzmo, allowing you to call stored procedures for example.
      - **< dataset_id >**: `object` - The dataset (securable) ID that you want to override.
        - **schema**: `string` - The new schema that this dataset should connect to.
        - **table**: `string` - The new table that this dataset should connect to.
        - **sql**: `string` - The new SQL statement to use (only for SQL datasets).
          Note that the columns returned in the new query need to conform to the same schema as the original dataset.
- **filters**: `array<object>` - List of data filters to apply when data queries are performed with this authorization. See **"Merging of data filters for Embed tokens"** at the start of [Create Authorization](/api/createAuthorization.md) for more information about filtering behaviour when Embed tokens query data.
  * This can be used with multi-tenanted datasets to ensure end-clients can only access their own data. Note that the use of parameter filters (see Authorization property `parameter_overrides`) is usually a better approach, however.
  * You can also use the filters property to specify initialization filters on one or more dashboard items. These filters will be applied as a pre-selection when the dashboard item is loaded, but can be modified by the end-user in the respective dashboard item.
  - **clause**: `"where" | "having"` - Timing of application of the filter. Possible values:
    * `where` - Applied before aggregation/grouping, e.g. only select rows with a specific price.
    * `having` - Applied after aggregation/grouping, e.g. only select groups in which the total price exceeds a specific value
  - **origin**: `"global" | "chart" | "initialization"` - Level to apply the filter. Possible values:
    * `global` - Static filter to exclude specific rows from users for the complete dataset
    * `chart` - Static filter to exclude specific rows from users for a single chart
    * `initialization` - Initialize a filter selection within a dashboard item to a particular value, where the end-user can further customize the filter selection in the item
  - **securable_id**: `string (uuid)` - * In case of `global` or `chart` filter: Dataset ID to filter.
    * In case of `initialization` filter:
    * In case of a "chart" dashboard item (e.g. column chart, line chart, etc.), the `securable_id` should be the Dataset ID of the column to initialize on.
    * "Filter" dashboard items (e.g. date picker, dropdown filter, etc.) do not require a securable_id to be specified, as the initialization filter will automatically apply on all columns in the filter item's slot.
  - **column_id**: `string (uuid)` - * In case of `global` or `chart` filter: Column ID to filter.
    * In case of `initialization` filter:
    * In case of a "chart" dashboard item (e.g. column chart, line chart, etc.), the `column_id` should be the Column ID to initialize on.
    * "Filter" dashboard items (e.g. date picker, dropdown filter, etc.) do not require a column_id to be specified, as the initialization filter will automatically apply on all columns in the filter item's slot.
  - **level**: `integer` - In case of filtering on a hierarchy or date(time) column - the Hierarchy or Date(time) level to filter on.
    This can be either a datetime level (1 = years, ..., 5 = days, ..., 9 = milliseconds), which defaults to the column's lowest date(time) level if not specified, or a hierarchy level (1 = top level, and default value if not specified).
  - **chart_id**: `string (uuid)` - In case of `initialization` or `chart` filter: dashboard Item ID to initialize. This can be found in the dashboard item's settings menu in the editor.
  - **aggregation**: `object` - Aggregation to apply to the column. Only used for filters with property `clause` set to `having` (i.e. post-aggregation filters).
    - **type**: `string` - Type of aggregation to apply.
    - **dataset_id**: `string (uuid)` - The Dataset ID for the weight or denominator column. Only used for aggregation types `weightedaverage` or `rate`.
    - **column_id**: `string (uuid)` - The Column ID of the weight or denominator column. Only used for aggregation types `weightedaverage` or `rate`.
    - **level**: `integer` - The Hierarchy / Date(time) level of the hierarchy / date(time) column used as weight or denominator column.
      This can be either a datetime level (1 = years, ..., 5 = days, ..., 9 = milliseconds), which defaults to the column's lowest date(time) level if not specified, or a hierarchy level (1 = top level, and default value if not specified).
  - **expression**: `string` - Which filter expression to apply. See table in [this Academy article](https://academy.luzmo.com/article/rfgtd5fs#filters) for more details about the available filter expressions.
  - **value**: `number | string | boolean | array` - Value(s) to filter on. Make sure to specify the right type of value for the filter expression you're using as well as the data type of the column filtered on. For example, if you're using the `? in ?` filter expression on a numeric column, you should provide an array of numeric values to filter on (e.g. `[1, 2]`).
- **environment**: `"null" | "production" | "acceptance" | "development" | "qa"` - Used to control which dashboard version is shown. Valid options are: `null`, `production`, `acceptance`, `development`, `qa`. If explicitly set to `null`, the latest dashboard version will always be shown when embedding with this token. If not specified or set to `"production"`, it will show the published production version, or the latest version if it doesn't exist. If set to `development`, `acceptance` or `qa`, it will show the corresponding published version, or the latest version if it doesn't exist.
  - Default: `"production"`
- **currency_id**: `string` - Overrides the displayed currency symbol on the dashboards, for all currency columns. Expects a currency_id in the form of an [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code, for example: EUR or USD.
- **theme**: `object` - Optional JSON definition of a theme to apply to the dashboard. See [this Academy article](https://academy.luzmo.com/article/d73314lu) for more information.
- **css**: `string` - Optional CSS override to apply to the dashboard. The CSS gets appended to the existing CSS overrides in the dashboard. An example can be seen in [this Academy article](https://academy.luzmo.com/article/hmvy5pwz).
- **feature_overrides**: `array<string>` - Enable/disable certain features for the Embed user. See [this Academy article](https://academy.luzmo.com/article/n51vdanw) for a list of all available feature flags.
- **hidden_columns**: `array<string (uuid)>` - List of dataset column ids to be hidden in an embedded dashboard. This will hide the columns from the end-user in e.g. the embedded editor, but they can still be queried from existing dashboard items.
- **metadata**: `object` - Use the `metadata` property to specify optional Viewer metadata. This must be a valid JSON object with a maximum length of 200k characters.

  *For Authorization tokens with deprecated type 'sso', you can also use the metadata property to override parameter values of parameterized filters.*
  * *To clear parameterized filter(s) completely (i.e. not apply them), override its value to: `{"< parameter name >": {"clear": true}}`*
  * *To mark sensitive parameters that should not be logged, like JWT or authentication tokens, store it as an object with the sensitive property set: `{"< parameter name >": {"sensitive": true, "value": "..."}}`*
  * *To mark a parameter as sticky to make sure its value is always used in future scheduled exports and alerts created by this token, rather than an updated value from a newer token for the same username, set: `{"< parameter name >": {"sticky": true, "value": "..."}}}`*
- **ip**: `array<string>` - List of IP addresses or subnets. Leave empty to disable IP whitelisting (default behavior).
  Eg.: `["123.45.67.89", "123.45.66.0/4", "2001:db8:0:1:1:1:1:1"]`
- **screenmode**: `"desktop" | "tablet" | "mobile" | "largeScreen" | "fixed"` - Screen mode of dashboards to use. If empty, the window size will be used to determine the screen mode (default behavior).
- **password**: `string` - Password of the user. Only used when requesting a login token.
- **iq**: `object` - Extra properties to customize interactions with Luzmo IQ.
  - **context**: `string` - Additional prompt instructions that will be provided to the Luzmo IQ LLM when answering user questions. These instructions will be given higher priority than user messages. However, the LLM may disregard them if they conflict with safety rules.

    Examples:

    - The user's name is Alice. You should greet the user by name during the first interaction.
    - If a question refers to project cost without specifying a specific cost column, default to using the column "actualCost".
    - Always request an explicit time range when a time range is needed to answer a question and cannot be inferred.

## Response Properties

- **id**: `string (uuid)`
- **token**: `string`
- **user_id**: `string (uuid)`
- **type**: `"embed" | "api" | "login" | "sso"`
- **environment**: `"null" | "production" | "acceptance" | "development" | "qa"`
- **expiry**: `string (date-time)`
- **inactivity_interval**: `integer`
- **last_used_at**: `string (date-time)`
- **created_at**: `string (date-time)`
- **updated_at**: `string (date-time)`
- **deleted_at**: `string (date-time)`
- **username**: `string`
- **name**: `string`
- **email**: `string (email)`
- **suborganization**: `string`
- **role**: `"designer" | "owner" | "viewer"`
- **access**: `object`
  - **collections**: `array<object>`
    - **id**: `string (uuid)`
    - **inheritRights**: `"read" | "use" | "modify" | "own"`
  - **datasets**: `array<object>`
    - **id**: `string (uuid)`
    - **rights**: `"read" | "use" | "modify" | "own"`
  - **dashboards**: `array<object>`
    - **id**: `string (uuid)`
    - **rights**: `"read" | "use" | "modify" | "own"`
- **filters**: `array<object>`
  - **clause**: `"where" | "having"`
  - **origin**: `"global" | "chart" | "initialization"`
  - **securable_id**: `string (uuid)`
  - **column_id**: `string (uuid)`
  - **level**: `integer`
  - **chart_id**: `string (uuid)`
  - **aggregation**: `object`
    - **type**: `string`
    - **dataset_id**: `string (uuid)`
    - **column_id**: `string (uuid)`
    - **level**: `integer`
  - **expression**: `string`
  - **value**: `number | string | boolean | array`
- **hidden_columns**: `array<string (uuid)>`
- **theme**: `object`
- **css**: `string`
- **metadata**: `object`
- **currency_id**: `string`
- **parameter_overrides**: `object`
- **feature_overrides**: `array<string>`
- **description**: `string`
- **ip**: `array<string>`
- **iq**: `object`
  - **context**: `string`

## Required Access Rights

- Logged-in User

## SDK Usage

Luzmo provides official SDKs that handle authentication and request formatting automatically. You can also use any HTTP client (curl, fetch, axios, etc.) to make requests directly to the API.

### Shell / cURL

Base URL: `https://api.luzmo.com` (EU), `https://api.us.luzmo.com` (US), or your VPC-specific API Host URL

```bash
curl https://api.luzmo.com/0.1.0/authorization  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "create",
  "version": "0.1.0",
  "key": "<your Luzmo API key>",
  "token": "<your Luzmo API token>",
  "properties": {
    "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"
        }
      ]
    }
  }
}
EOF
```

### Node SDK

Install: `npm install @luzmo/nodejs-sdk`

```javascript
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 (default) or https://api.us.luzmo.com or your VPC-specific address >'
});

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"
        }
      ]
    }
  }
);
```

### Java SDK

Install: `pkg:maven/com.luzmo/sdk`

```java
Luzmo client = new Luzmo(
  "<your Luzmo API key>',
  "<your Luzmo API token>',
  "< https://api.luzmo.com (default) or https://api.us.luzmo.com or your VPC-specific address >"
);

JSONObject response = client.create("authorization",
  ImmutableMap.of(
    "type" , "embed",
    "username" , "<A unique and immutable identifier for your user>",
    "name" , "<username>",
    "email" , "<user_email>",
    "suborganization" , "<a suborganization name>",
    "access" , ImmutableMap.of(
      "collections" , ImmutableList.of(
        ImmutableMap.of(
          "id" , "<collection_id>",
          "inheritRights" , "use"
        )
      ),
      "datasets" , ImmutableList.of(
        ImmutableMap.of(
          "id" , "<dataset_id>",
          "rights" , "use"
        )
      ),
      "dashboards" , ImmutableList.of(
        ImmutableMap.of(
          "id" , "<dashboard_id>",
          "rights" , "use"
        )
      )
    )
  )
);
```

### .NET SDK

Install: `dotnet add package LuzmoSDK`

```csharp
Luzmo client = new Luzmo(
  "<your Luzmo API key>',
  "<your Luzmo API token>',
  "< https://api.luzmo.com (default) or https://api.us.luzmo.com or your VPC-specific address >"
);

dynamic properties = new ExpandoObject();
properties.type = "embed";
properties.username = "<A unique and immutable identifier for your user>";
properties.name = "<username>";
properties.email = "<user_email>";
properties.suborganization = "<a suborganization name>";
properties.access = new {
  collections = new List<Object> {
    new {
      id = "<collection_id>",
      inheritRights = "use"
    }
    },
  datasets = new List<Object> {
    new {
      id = "<dataset_id>",
      rights = "use"
    }
    },
  dashboards = new List<Object> {
    new {
      id = "<dashboard_id>",
      rights = "use"
    }
    }
};

dynamic response = client.create("authorization", properties);

```

### Python SDK

Install: `pip install luzmo-sdk`

```python
from luzmo.luzmo import Luzmo
client = Luzmo(
  "<your Luzmo API key>',
  "<your Luzmo API token>',
  "< https://api.luzmo.com (default) or https://api.us.luzmo.com or your VPC-specific address >"
)

response = 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"
        }
      ]
    }
  }
)
```

### PHP SDK

Install: `composer require luzmo/luzmo-sdk-php`

```php
<?php
require 'vendor/autoload.php';
use Luzmo\Luzmo;

$client = Luzmo::initialize(
  '<your Luzmo API key>',
  '<your Luzmo API token>',
  '< https://api.luzmo.com (default) or https://api.us.luzmo.com or your VPC-specific address >'
);

$response = $client->create("authorization",
  array (
    'type' => "embed",
    'username' => "<A unique and immutable identifier for your user>",
    'name' => "<username>",
    'email' => "<user_email>",
    'suborganization' => "<a suborganization name>",
    'access' => array (
      'collections' => array (
        array (
          'id' => "<collection_id>",
          'inheritRights' => "use"
        )
      ),
      'datasets' => array (
        array (
          'id' => "<dataset_id>",
          'rights' => "use"
        )
      ),
      'dashboards' => array (
        array (
          'id' => "<dashboard_id>",
          'rights' => "use"
        )
      )
    )
  )
);
?>
```

## Request Body Examples

The following examples show the complete request body structure for HTTP/cURL requests. Each example includes the outer wrapper property (`properties`) that contains the actual parameters.

> **For SDKs**: Pass only the inner content (without the outer wrapper) to the SDK methods. For example, if the JSON shows `{ "properties": { "name": {"en": "My authorization"} } }`, an SDK would use something like this: `client.create('authorization', { name: { en: "My authorization" } })`.

### Create an embed token

**Request properties:**

```json
{
  "properties": {
    "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"
        }
      ]
    }
  }
}
```

**Expected response for this request (HTTP 200)**

```json
{
  "id": "c6dcefe7-a0f8-4837-9050-ba4617691a28",
  "token": "HXlTLT4mj8Ajmw5QMegcloMps3d1zxopoa1caC8r2nFBdvpm3POURhvRYX6jSariWAWmet7YURSyzjK1KhUn8UZ4ItdlgzlNCklqX2LNiZ5dVL8S1MozHpWzQ0ILS0qkLhb5e20YmxAc2HOFJmOgbg",
  "user_id": "477086f8-2ad2-4e5f-8aaf-de209f69b9bb",
  "type": "embed",
  "environment": "production",
  "expiry": "2024-12-31T00:00:00.000Z",
  "inactivity_interval": null,
  "last_used_at": "2024-08-13T08:29:30.000Z",
  "created_at": "2024-08-13T08:29:30.099Z",
  "updated_at": "2024-08-13T08:29:30.099Z",
  "deleted_at": null,
  "username": "<A unique and immutable identifier for your user>",
  "name": "<username>",
  "email": "<user_email>",
  "suborganization": "<a suborganization name>",
  "role": "viewer",
  "access": {
    "datasets": [
      {
        "id": "<dataset_id>",
        "rights": "use"
      }
    ],
    "dashboards": [
      {
        "id": "<dashboard_id>",
        "rights": "use"
      }
    ]
  },
  "hidden_columns": [],
  "filters": null,
  "theme": null,
  "css": null,
  "currency_id": null,
  "metadata": null,
  "parameter_overrides": null,
  "feature_overrides": null,
  "description": null,
  "ip": null,
  "iq": {
    "context": "<Luzmo IQ context prompt>"
  }
}
```

### Create a Login token

**Request properties:**

```json
{
  "properties": {
    "name": "Technical User",
    "email": "technical-user@luzmo.com",
    "password": "password"
  }
}
```

### Create an API token

**Request properties:**

```json
{
  "properties": {
    "type": "api"
  }
}
```

### Specify parameter overrides when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "<A unique and immutable identifier for your user>",
    "name": "<user name>",
    "email": "<user email>",
    "suborganization": "<a suborganization name>",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "parameter_overrides": {
      "Country": [
        "Spain"
      ],
      "<parameter name>": [
        "<value to apply>",
        "<other value to apply>"
      ],
      "<parameter to clear>": {
        "clear": true
      }
    }
  }
}
```

### Specify a global filter when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "filters": [
      {
        "clause": "where",
        "origin": "global",
        "securable_id": "< dataset id of a dataset used in the dashboard >",
        "column_id": "< column id of a column in a dataset used in the dashboard >",
        "expression": "? = ?",
        "value": "< value to be applied to the expression >"
      }
    ]
  }
}
```

### Specify a chart filter when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "filters": [
      {
        "clause": "where",
        "origin": "chart",
        "securable_id": "< dataset id of a dataset used in the dashboard >",
        "column_id": "< column id of a column in a dataset used in the dashboard >",
        "chart_id": "< chart id of an object contained in the dashboard >",
        "expression": "? = ?",
        "value": "< value to be applied to the expression >"
      }
    ]
  }
}
```

### Specify an initialization filter on a dropdown or slicer filter item when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "filters": [
      {
        "clause": "where",
        "origin": "initialization",
        "chart_id": "< chart id of a filter object contained in the dashboard >",
        "expression": "? between ?",
        "value": [
          [
            "2023-11-01T00:00:00.000Z",
            "2023-12-01T00:00:00.000Z"
          ]
        ]
      }
    ]
  }
}
```

### Specify an initialization filter on a datefilter item when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "filters": [
      {
        "clause": "where",
        "origin": "initialization",
        "chart_id": "< chart id of a filter object contained in the dashboard >",
        "expression": "next_now",
        "value": {
          "unit": 4,
          "quantity": 3
        }
      }
    ]
  }
}
```

### Specify an initialization filter on a slider item when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "filters": [
      {
        "clause": "where",
        "origin": "initialization",
        "chart_id": "< chart id of a filter object contained in the dashboard >",
        "expression": "? >= ?",
        "value": "2024-01-01T00:00:00.000Z"
      },
      {
        "clause": "where",
        "origin": "initialization",
        "chart_id": "< chart id of a filter object contained in the dashboard >",
        "expression": "? <= ?",
        "value": "2025-01-01T00:00:00.000Z"
      }
    ]
  }
}
```

### Specify an initialization filter on a chart when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "filters": [
      {
        "clause": "where",
        "origin": "initialization",
        "chart_id": "< chart id of a chart object contained in the dashboard >",
        "expression": "? = ?",
        "column_id": "< id of the column to apply the filters to >",
        "securable_id": "< id of the dataset that the column belongs to >",
        "value": [
          "< value to be applied to the expression >"
        ]
      }
    ]
  }
}
```

### Specify a having filter on a dashboard level when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "filters": [
      {
        "clause": "having",
        "origin": "global",
        "column_id": "< id of the column to apply the filters to >",
        "securable_id": "< id of the dataset that the column belongs to >",
        "aggregation": {
          "type": "sum"
        },
        "expression": ">",
        "value": 100
      }
    ]
  }
}
```

### Specify a having filter on a chart level when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "filters": [
      {
        "clause": "having",
        "origin": "chart",
        "column_id": "< id of the column to apply the filters to >",
        "securable_id": "< id of the dataset that the column belongs to >",
        "chart_id": "<id of the chart that the filter will be applied to>",
        "aggregation": {
          "type": "sum"
        },
        "expression": ">",
        "value": 100
      }
    ]
  }
}
```

### Specify a theme override when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "theme": {
      "font": {
        "fontSize": 15,
        "fontFamily": "Open Sans"
      },
      "type": "custom",
      "title": {
        "bold": false,
        "align": "left",
        "border": false,
        "italic": true,
        "underline": false,
        "fontSize": 20,
        "lineHeight": 40
      },
      "colors": [
        "#00a8b7",
        "rgb(232,228,228)",
        "rgba(226,180,12,0.5)"
      ],
      "borders": {
        "bordercolor": "rgba(0,0,0,.1)",
        "borderstyle": "none",
        "borderradius": "3px",
        "border-topwidth": "1px",
        "border-leftwidth": "1px",
        "border-rightwidth": "1px",
        "border-bottomwidth": "1px"
      },
      "margins": [
        10,
        10
      ],
      "boxShadow": {
        "size": "S",
        "color": "rgb(2,34,32)"
      },
      "mainColor": "#004cb7",
      "background": "#EEF3F6",
      "itemsBackground": "#ffffff",
      "editModeBackground": "#ececec",
      "axis": {
        "fontSize": 13
      },
      "legend": {
        "type": "normal"
      },
      "tooltip": {
        "background": "rgba(255,255,255,1)",
        "fontSize": 13
      },
      "editBackground": "rgb(222, 226, 229)",
      "editDarkOrLight": "light-edit",
      "darkOrLight": "light"
    }
  }
}
```

### Specify a CSS override when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "css": "body { background-color: red !important; }"
  }
}
```

### Specify a feature override when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "feature_overrides": [
      "!flag_export"
    ]
  }
}
```

### Specify a locale when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "locale_id": "es"
  }
}
```

### Specify a currency override when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "currency_id": "EUR"
  }
}
```

### Specify a timezone override when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "timezone_id": "America/New_York"
  }
}
```

### Specify column(s) to hide when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "hidden_columns": [
      "<column_id_1>",
      "<column_id_2>"
    ]
  }
}
```

### Specify AWS Athena connection override when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "account_overrides": {
      "<your connection_id>": {
        "properties": {
          "host": "<new_s3_results_bucket_endpoint>",
          "key": "<new_IAM_access_id>",
          "token": "<new_IAM_access_key>",
          "region": "<new_Athena_region>",
          "workgroup": "<new_Athena_workgroup>"
        }
      }
    }
  }
}
```

### Specify BigQuery connection override when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "account_overrides": {
      "<your connection_id>": {
        "key": "new-email@test.iam.gserviceaccount.com",
        "token": "-----BEGIN PRIVATE KEY----- <obfuscated> ----- END PRIVATE KEY-----"
      }
    }
  }
}
```

### Specify BigQuery dataset(s) connection override when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "account_overrides": {
      "<your connection_id>": {
        "datasets": {
          "< Luzmo dataset ID>": {
            "sql": "SELECT ... FROM ..."
          }
        }
      }
    }
  }
}
```

### Specify Clickhouse connection override when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "account_overrides": {
      "<your connection_id>": {
        "host": "<The new database host URL to connect to>",
        "key": "<username>",
        "token": "<password>"
      }
    }
  }
}
```

### Specify Clickhouse dataset(s) connection override when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "account_overrides": {
      "<your connection_id>": {
        "datasets": {
          "< Luzmo dataset ID>": {
            "table": "table"
          }
        }
      }
    }
  }
}
```

### Specify Databricks connection override when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "account_overrides": {
      "<your connection_id>": {
        "properties": {
          "token": "Override User Access Token",
          "httppath": "Override HTTP Path",
          "serverhostname": "Override Server Host Name"
        }
      }
    }
  }
}
```

### Specify Databricks dataset(s) connection override when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "account_overrides": {
      "<your connection_id>": {
        "datasets": {
          "< dataset id>": {
            "schema": "< Override Databricks Catalog >",
            "table": "< Override Databricks Schema >.< Override Databricks Table >"
          }
        }
      }
    }
  }
}
```

### Specify ElasticSearch connection override when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "account_overrides": {
      "<your connection_id>": {
        "host": "<The new elasticsearch host URL to connect to>",
        "key": "<username>",
        "token": "<password>"
      }
    }
  }
}
```

### Specify ElasticSearch dataset(s) connection override when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "account_overrides": {
      "<your connection_id>": {
        "datasets": {
          "< dataset id>": {
            "table": "index name"
          }
        }
      }
    }
  }
}
```

### Specify MariaDB connection override when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "account_overrides": {
      "<your connection_id>": {
        "host": "<The new database host URL to connect to>",
        "user": "<username>",
        "password": "<password>"
      }
    }
  }
}
```

### Specify MariaDB dataset(s) connection override when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "account_overrides": {
      "<your connection_id>": {
        "datasets": {
          "< Luzmo dataset ID>": {
            "sql": "SELECT ... FROM ..."
          }
        }
      }
    }
  }
}
```

### Specify MongoDB connection override when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "account_overrides": {
      "<your connection_id>": {
        "host": "<The new database host URL to connect to>",
        "key": "<username>",
        "token": "<password>"
      }
    }
  }
}
```

### Specify MongoDB dataset(s) connection override when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "account_overrides": {
      "<your connection_id>": {
        "datasets": {
          "< Luzmo dataset ID>": {
            "schema": "database",
            "table": "collection"
          }
        }
      }
    }
  }
}
```

### Specify MySQL connection override when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "account_overrides": {
      "<your connection_id>": {
        "host": "<The new database host URL to connect to>",
        "user": "<username>",
        "password": "<password>"
      }
    }
  }
}
```

### Specify MySQL dataset(s) connection override when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "account_overrides": {
      "<your connection_id>": {
        "datasets": {
          "< Luzmo dataset ID>": {
            "sql": "SELECT ... FROM ..."
          }
        }
      }
    }
  }
}
```

### Specify Oracle connection override when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "account_overrides": {
      "<your connection_id>": {
        "host": "<The new database host URL or connection string>",
        "key": "<username>",
        "token": "<password>"
      }
    }
  }
}
```

### Specify PostgreSQL connection override when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "account_overrides": {
      "<your connection_id>": {
        "host": "<The new database host URL to connect to>",
        "user": "<username>",
        "password": "<password>"
      }
    }
  }
}
```

### Specify PostgreSQL dataset(s) connection override when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "account_overrides": {
      "<your connection_id>": {
        "datasets": {
          "< Luzmo dataset ID>": {
            "sql": "SELECT ... FROM ..."
          }
        }
      }
    }
  }
}
```

### Specify Presto connection override when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "account_overrides": {
      "<your connection_id>": {
        "host": "<new_https_endpoint>",
        "port": "<new_https_port>",
        "database": "<new_collection>",
        "user": "<new_username>",
        "password": "<new_password>"
      }
    }
  }
}
```

### Specify Presto dataset(s) connection override when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "account_overrides": {
      "<your connection_id>": {
        "datasets": {
          "< Luzmo dataset ID>": {
            "sql": "SELECT ... FROM ..."
          }
        }
      }
    }
  }
}
```

### Specify Redshift connection override when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "account_overrides": {
      "<your connection_id>": {
        "host": "<The new database host URL to connect to>",
        "user": "<username>",
        "password": "<password>"
      }
    }
  }
}
```

### Specify Redshift dataset(s) connection override when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "account_overrides": {
      "<your connection_id>": {
        "datasets": {
          "< Luzmo dataset ID>": {
            "sql": "SELECT ... FROM ..."
          }
        }
      }
    }
  }
}
```

### Specify SAP HANA connection override when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "account_overrides": {
      "<your connection_id>": {
        "host": "<The new database host URL to connect to>",
        "key": "<username>",
        "token": "<password>"
      }
    }
  }
}
```

### Specify Snowflake connection override when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "account_overrides": {
      "<your connection_id>": {
        "properties": {
          "host": "<New account name of your Snowflake account to connect to>",
          "key": "<New username of Snowflake user>",
          "private_key": "<New private key, in case key-pair auth is used>",
          "token": "<Passphrase used to protect private key, in case key-pair auth is used, or new password of Snowflake user>",
          "warehouse": "<New Snowflake Warehouse to use to query data>",
          "role": "<New Snowflake user Role to use to query data>"
        }
      }
    }
  }
}
```

### Specify Snowflake dataset(s) connection override when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "account_overrides": {
      "<your connection_id>": {
        "datasets": {
          "< Luzmo dataset ID>": {
            "sql": "SELECT ... FROM ..."
          }
        }
      }
    }
  }
}
```

### Specify SQL Server connection override when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "account_overrides": {
      "<your connection_id>": {
        "host": "<The new database host URL to connect to>",
        "user": "<username>",
        "password": "<password>"
      }
    }
  }
}
```

### Specify SQL Server dataset(s) connection override when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "account_overrides": {
      "<your connection_id>": {
        "datasets": {
          "< Luzmo dataset ID>": {
            "sql": "SELECT ... FROM ..."
          }
        }
      }
    }
  }
}
```

### Specify Azure Synapse connection override when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "account_overrides": {
      "<your connection_id>": {
        "host": "<The new database host URL to connect to>",
        "user": "<username>",
        "password": "<password>"
      }
    }
  }
}
```

### Specify Trino connection override when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "account_overrides": {
      "<your connection_id>": {
        "host": "<new_https_endpoint>",
        "port": "<new_https_port>",
        "database": "<new_collection>",
        "user": "<new_username>",
        "password": "<new_password>"
      }
    }
  }
}
```

### Specify Trino dataset(s) connection override when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "account_overrides": {
      "<your connection_id>": {
        "datasets": {
          "< Luzmo dataset ID>": {
            "sql": "SELECT ... FROM ..."
          }
        }
      }
    }
  }
}
```

### Specify Plugin connection override when creating an embed token

**Request properties:**

```json
{
  "properties": {
    "type": "embed",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "access": {
      "collections": [
        {
          "id": "<collection_id>",
          "inheritRights": "use"
        }
      ]
    },
    "account_overrides": {
      "<your connection_id>": {
        "properties": {
          "< custom authentication property ID>": "< the new custom authentication property value >"
        }
      }
    }
  }
}
```

### Create an embed token with a Luzmo IQ context

**Request properties:**

```json
{
  "properties": {
    "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"
        }
      ]
    },
    "iq": {
      "context": "<Luzmo IQ context prompt>"
    }
  }
}
```

## Generic Response Formats

These responses are generic endpoint-level formats (for example common error payloads) and are not specific to one request example.

### A bad request error message returned by the API. (HTTP 400)

```json
{
  "type": {
    "code": 400,
    "description": "Bad Request"
  },
  "message": "Detailed error message"
}
```

### An internal server error message returned by the API. (HTTP 500)

```json
{
  "type": {
    "code": 500,
    "description": "Internal Server Error"
  },
  "message": "Detailed error message"
}
```

## Related Operations

- [Search Authorization](https://developer.luzmo.com/api/searchAuthorization.md)
- [Delete Authorization](https://developer.luzmo.com/api/deleteAuthorization.md)


---

## Sitemap

- [Official best practices and implementation guidelines](https://developer.luzmo.com/AGENTS.md)
- [Overview of all docs pages](https://developer.luzmo.com/llms.txt)
- [Full index of all documentation](https://developer.luzmo.com/llms-full.txt): Complete list of every doc page in markdown format with descriptions — use to discover relevant docs from user queries