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

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