Signed embedding (BETA)

Signed embedding allows you to securely embed Hex apps into your own website or web application without requiring your users to authenticate into Hex. You can optionally implement row-level security to ensure your users can access only their unique data.

info

• Available on the Enterprise plan.
• Contact [email protected] to get access to Signed Embedding.
• The following features are not supported in embedded apps: Notebook editing, Commenting, Explore, and Snapshots.
• Signed embedding is currently in Beta.

Setting up signed embedding

To use signed embedding, the feature must be enabled on your Hex workspace. For assistance, contact your account team or [email protected].

Enable signed embedding on a project

From the Share modal in the top right corner of your Hex project, toggle on Allow signed embedding.

Enabling signed embedding will allow API clients to generate the single-use signed URLs for your project that you’ll embed in your web application.

tip

For Hex projects you plan to embed, we recommend requiring reviews and limiting the number of users with Can edit or higher permissions on the project.

Implement row-level security

You can optionally configure your signed embedding project to dynamically filter the data for each user based on hex_user_attributes that you pass in your API request.

To do so, you must add a parameterized SQL query that filters your base data on one or more hex_user_attributes in a where clause. You also must specify these hex_user_attributes in the Variables sidebar of your Hex Project.

Test row-level security with hex_user_attribute preview values

When you specify your hex_user_attributes in the Variables sidebar, you will be prompted to enter a preview value for each attribute. These values will be used to run the app in the Notebook view and App builder so that you can see what the app will look like to a speciifc embed user.

Arrange and publish your app

Use the App builder tab to arrange your app how you would like it to appear for your users. You can remove the project title and other metadata from App settings > Display options in the right hand sidebar of the App builder.

Once you're satisfied with your app, publish the latest version. If you implemented row-level security with hex_user_attributes, the published app should fail to render data in any cells that are built from the filtered data source. Without valid hex_user_attribute values passed via API, these parts of your app will not render.

Implement Hex createPresignedUrl API in your web app

Once you've published your Hex app, you can implement Hex's createPresignedUrl public API endpoint server-side to securely embed the app in your website or web application.

Hex’s createPresignedUrl public API endpoint accepts a workspace token, base URL for your Hex workspace, and Hex project id, and returns a single-use signed URL that you can inject into an iframe. The presigning ensures each URL can be viewed exactly once, protecting against link sharing and session replay attacks. This allows you to securely embed Hex content without requiring your web application users to login to Hex.

You can optionally pass hexUserAttributes in your API request, in order to implement row-level security or other data personalization.

Generate a workspace token

From Settings > API keys, a Workspace Admin will need to create a new workspace token with your desired expiration (“No Expiry” is recommended) and the "Create embedded links" API scope.

API request implementation

warning

The createPresignedUrl must be implemented server-side in a secure part of your web application's code. Implementing the API client-side will create a security vulnerability.

To implement the API, set the BASE_HEX_API_URL key equal to your Hex workspace's base URL. For most customers, this will be https://app.hex.tech/api/v1. For single tenant, EU multi tenant, and HIPAA multi tenant customers, replace "app.hex.tech" with your custom URL (e.g. "atreides.hex.tech", "eu.hex.tech").

Set the TOKEN key equal to the workspace token you generated in the step above.

Set the PROJECT_ID key equal to the project id associated with your app. You can find the project id in the Variables sidebar of the Hex project.

In the request body:

• Optionally specify any hex_user_attributes that will be used to implement row-level security.
• Optionally pass in additional scope to grant specific permissions to your users viewing the embedded app. For example, allow users to export a CSV from a table by passing in scope: ["EXPORT_CSV"]).
• Optionally set displayOptions: { noEmbedFooter: true, noEmbedOutline: true } options in the request body to customize the content display in your iframe.
• Optionally pass in any desired inputParameters values, which can be any JSON value and will be passed to the relevant input parameter(s) on your published app as a string.

Example API call

import requests

BASE_HEX_API_URL = 'https://app.hex.tech/api/v1'
# this token is invalid
TOKEN = '812d64548435bb81f6e974a25bf841fa13af1c68b89b2f453d734d7d272daa3c70e43bf1a0460687a7ac76ba085300b5'
PROJECT_ID = 'd148ce6e-fc3b-40cb-9bdc-52b02d470061'
body = {
  "userAttributes": {
    "userId": "12345",
    "userRole": "admin",
    "userCountry": "MEX"
  },
  "scope": ["EXPORT_PDF", "EXPORT_CSV"],
  "expiresIn": 30000,
  "displayOptions": {
    "noEmbedFooter": true,
    "noEmbedOutline": true
  }
}
response = requests.post(
url=f"{BASE_HEX_API_URL}/embedding/createPresignedUrl/{PROJECT_ID}",
json=body, headers={"Authorization" : f"Bearer {TOKEN}"}
)
print(response.json().get("url"))

If configured correctly, this call will generate a single-use signed URL that can be inserted into an iframe tag to embed in your web applications.

Common (Non-URL) API responses

400/401/403: These API responses indicate an unauthorized, forbidden, or otherwise bad request. The cause for this response could be any of the following (non-exhaustive):

• No authentication method: ensure that there is an Authorization: Bearer {token} header in the request
• Invalid token, or token without the create embedded links scope: this can be configured in the Workspace token settings
• Expired token
• Incorrect baseUrl or projectId
• Signed embedding isn't turned on for the project

424: A 424 response indicates a malformed request. If you see this response, make sure to confirm the following:

• Content-type: application/json is being set on the request headers
• The request body includes the required parameters (specified in API request setup section)
• The project is published

Optimizing app load time for signed embedding

Hex offers built-in caching with hex_user_attributes, as well as project configuration options to help you strike the optimal balance between data freshness and app load time for your embed users.

How caching works for signed embedding with hex_user_attributes

For projects with signed embedding enabled, Hex will cache results for each unique combination of hex_user_attributes that are referenced in the Hex project. This ensures data security across distinct combinations of hex_user_attributes, while enabling the performance benefits of a shared cache for users with identical credentials.

For example, if User A visits your signed embedded app with hex_user_attributes: { orgId: 1 } , they would share a cache with User B who has the same attributes hex_user_attributes: { orgId: 1 } . However, User C with different attributes hex_user_attributes: { orgId: 2 } will have their own cached results.

tip

Only hex_user_attributes that are both defined in the Variables tab and referenced in the Hex project will be used to determine which cache to use.

For example, if the project defines and references only hex_user_attributes.orgId then two embed users with hex_user_attributes: {orgId: 1, userId: 123} and hex_user_attributes: {orgId: 1, userId: 456} would be able to share a cache, since both embed users’ effective hex_user_attributes would be hex_user_attributes: {orgId: 1}.

Use query caching and dataframe SQL parameterization for performant row-level security

If you’re using hex_user_attributes to implement row-level security on warehouse data for your embedded app, we generally recommend leveraging our query caching and dataframe SQL features to optimize embedded app runtime. These are optional strategies you can implement in your Hex project to ensure your embed users experience the shortest possible app load time by relying on cached results, and receive fresh data at your specified frequency.

To implement this strategy, start by creating a data connection SQL cell base_data that queries the base data for all your embed users.

warning

This base SQL cell should not be added to your app, as that would expose all data to all your embed users.

Hex stores the output of this SQL cell in the project memory, which means subsequent project runs do not need to re-run this query from scratch. You can specify the SQL cache timeout (i.e. the period where cached results are considered valid) by following the instructions in Ensure data freshness for signed embedding.

Then, create a dataframe SQL cell that queries the output of your first SQL cell, and filters the data using the hex_user_attributes variable in a where clause.

By setting the data source to Dataframes, you are running this new SQL query against the cached output of your first SQL cell, rather than running the query as a CTE directly against your warehouse.

info

If the results from your initial data connection SQL cell are too large to fit within your project’s memory limits, this strategy will not work for you. You will instead need to parameterize your initial data connection SQL query.

Ensure data freshness for signed embedding

You can configure the data freshness setting in the App builder to specify how frequently your cache should be considered stale.

Then, set up a scheduled run at the same frequency as your data freshness setting.

Troubleshooting and Technical FAQ

Why is my embedded app not rendering in Hex?

• Published apps with hex_user_attributes require the correct attributes to be passed via API in order to render. “Preview Values” only apply to the Notebook, App builder and Publish preview views. A published app with row-level security that is being used for embedding cannot also be viewed in Hex.

Why isn't my embedded app getting filtered correctly by values I passed in the API?

• Confirm that the hex_user_attributes are specified in the Variables tab. Any hex_user_attributes you pass via API that are not specified in the Variables tab are ignored, even if your project references them.

What Hex functionality is not available on embedded apps?

• View/edit the notebook - no near term plans to support
• Comments - no near term plans to support
• Explore - no near plans to support
• Snapshots - no near term plans to support