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 securtiy 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, enable Signed embedding.

Enabling signed embedding will allow API clients to generate the presigned URLs for your project that you’ll use to embed your project externally.

tip

For Hex projects you plan to embed in your own customer-facing product, we recommend limiting which users have Can edit or higher permissions on the project, and requiring reviews.

Implement row-level security

You can optionally configure your signed embedding project to dynamically display data to users based on their user attributes.

To do so, you must add a parameterized SQL query that filters the data using the hex_user_attributes that you pass from your website from the API request. You also must specify these hex_user_attributes in the Variables sidebar of your Hex Project.

Preview your app as a specific embed user

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 your app

Use the App Builder tab to arrange your App how you would like it to appear for your website users. You can remove the project Title and other metadata from the App Settings in the right hand sidebar of the App Builder.

Implement Hex createPresignedUrl API in your web app

Hex’s createPresignedUrl public API allows you to pass your website users’ identifying attributes to Hex, and receive a single-use signed URL that you can insert into an iframe tag to embed on your website. By implementing custom SQL row-level security with these identifying attributes in your Hex project, you can ensure your website users see only their data, without needing to log into Hex.

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 an option) and the Create embedded links API scope.

API request setup

Set your BASE_HEX_API_URL for the Hex workspace associated with your embedded App. 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 your TOKEN with the Workspace token generated in Implementing the createPresignedUrl API in your web app section above.

Set your PROJECT_ID to match the project associated with your embedded App. You can find the project ID in the Variables sidebar.

In the request body, specify the hex_user_attributes that will be used to accomplish the custom SQL row-level security that you set up above.

• Optionally pass in additional scope which will grant additional actions to embedded sessions. For example, 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 output of the embedded iFrame.
• Optionally pass in desired inputParameters values, which can be any JSON value and will be passed to the input parameter 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 on your website.

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}.

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 Environment tab. Any hex_user_attributes you pass via API that are not specified in the Environment 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