Embed a Widget Securely

To encrypt and protect sensitive embed configuration and render a Qrvey dashboard in a client environment, generate and deploy a secure token.

Secure Embedding Overview

In Qrvey Composer, you can embed a widget quickly. For example, you can embed a dashboard widget by selecting Embed from the options menu for a dashboard, copying its embedding code, and pasting it into a client-side application. However, this exposes an API key or any internal IDs in the client-side code, introducing a major security risk.

Do not expose either of the following:

• API key
• Internal IDs and configuration — Application IDs, user IDs, client IDs, and other internal references should be hidden from end users.

To secure this information while enabling embedded dashboards follow these guidelines:

• Encrypt sensitive configuration on the server side.
• Pass only a short-lived token to the client.

General Implementation

Follow these general steps to implement the token generation on a server for production, automate token issuance for authenticated users, and keep the client embed minimal with only a domain and the returned qvToken.

1. Build the widget configuration locally (the JSON you would otherwise paste inside the client embed).
2. Send the remaining sensitive configuration (such as row-level security parameters) to Qrvey's Widget Security Token endpoint from a server (or Postman for testing) with your API key in the request header.
3. You receive a secure JWT token that encrypts the sensitive parts of the configuration. Place that token into your client embed as the token property (so the client never holds the API key or raw IDs).

Widget Embedding Tutorial

The following tutorial video shows a basic end-to-end process for embedding a single Qrvey dashboard.

Tags: Widgets, Embedding

Encrypted Fields

When calling the token generation endpoint, include the widget configuration properties that should be encrypted. The most common required properties include the following:

Property	Description
appId	ID of the application containing the content to embed.
userId	Composer user who owns the application. This is the user who created the application, not the creator of the embedded asset.
clientId	End-user identifier for the person viewing the embedded dashboard.
orgId	Organization identifier.
api_key	Used when making an API call to obtain the JWT token. It is never passed inside the JSON body. It authenticates the server call as a header.

The domain property cannot be encrypted, and must be supplied from the client side.

Generate a Secure Widget Token

You can use Postman to generate a secure widget token.

1. Locate the endpoint in the API reference under Administration > Security > Generate Widget Security Token. Use the path appended to the domain URL in the guide to append to your Qrvey instance URL.

2. Prepare the request body.

   Copy your widget configuration JSON into the tool, then remove the domain and apiKey properties. The remainder serves as the request body in raw JSON format.

3. Authenticate the call. Use your Qrvey API key in the request header. Qrvey expects the API key under the header name x-api-key.

4. Send the POST request and retrieve the token.

   The response body contains a JSON object with a token property. That token is a JWT that securely contains the encrypted configuration. By default, the token is valid for one week. The expiration can be adjusted.

Render the Widget

To test the client-side rendering of the embedded widget, you can use an environment such as CodePen.

1. In the original widget embed snippet, keep the non-sensitive domain property with the client configuration.
2. Remove the API key placeholder.
3. Add a qv-token (case-sensitive) property.
4. Copy the entire secure widget token string and paste the string as the qv-token value.
5. Load the page. The embedded widget code decrypts the token and renders the dashboard without exposing private information on the client side.

Tips

• If the embed returns a permission error, confirm that the API key used in the server call is valid.
• Do not paste the actual API key into public client-side sandboxes like CodePen. Use a dummy value while testing the client portion.
• If the token fails to render, ensure you copied only the token string value (inside the quotes) and did not include surrounding JSON.
• Adjust the token expiration as needed. Shorter expiration cycles reduce exposure in case tokens are leaked.

Checklist

Before deploying, verify the following items:

• The API key does not appear in client-side code or public repositories.
• All sensitive configuration is encrypted into the token issued by the secure endpoint.
• Among client-side configuration values, only the domain is required for rendering. Non-sensitive configuration properties should not be encrypted, and can be passed back to the client as they are.
• Tokens are issued from a trusted server endpoint and delivered to the client at render time.

Additional Resources

Widget Embedding Overview Widget Authentication