Widget Embedding Quick Start

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

By exposing an API key or internal IDs in client-side code, you can introduce a major security risk. Client-side embedding code (an HTML script tag and JSON configuration) is visible to anyone who opens the browser developer tools or views source. Do not expose either of the following:

• API key
• Internal IDs and configuration — application IDs, owner user IDs, organization IDs and other internal references should be hidden from clients.

To secure this information while enabling embedded dashboards:

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

High-Level Aapproach

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. Remove the API key from that configuration and keep domain as a client-side property only.
3. Send the remaining sensitive configuration to Qrvey's "generate widget security token" endpoint from a server (or Postman for testing) with your API key in the request header.
4. Receive a secure JWT token that encrypts the sensitive parts of the configuration.
5. 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

Required 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 necessarily the creator of the embedded asset.
clientId	End user identifier for the person viewing the embedded dashboard.
orgId	Organization identifier.

• domain is not encrypted and must be supplied client-side.
• API key is never passed inside the JSON body. It authenticates the server call as a header.

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. The path displayed in the guide is appended to your Qrvey instance URL.

2. Prepare the request body.

   Copy your widget configuration JSON, then remove the domain and apiKey properties. You will send the rest as the request body in raw JSON format.

3. Authenticate the call.

   a. Use your Qrvey API key in the request header. Qrvey expects the API key under the header name xAPI-key.

   b. In Postman, set the authorization to an API key.

   c. Select API-key as the header key and your API key as the value.

4. Send the POST and retrieve the token.

   Send the request. 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.

Rendering Example

To perform the client-side act of rendering the embed, you can use an environment such as CodePen.

1. Start with the original widget embed snippet but remove any API key values.
2. Keep the non-sensitive domain property in the client configuration.
3. Add a property named QVToken (case sensitive as used by the embed) and paste the entire token string returned from the previous step as its value.
4. Load the page. The embed decrypts the token and render the dashboard without exposing private information client-side.

Tips

• If the embed returns a permission error, confirm the API key used in the server call is valid and the header is xAPI-key.
• Do not paste the actual API key into public client-side sandboxes like CodePen. Use a dummy value there 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 lifetime if you need longer or shorter validity. Shorter lifetimes reduce exposure if tokens are leaked.

Security Checklist

Before deploying, verify the following items:

• API key does not appear in client-side code or public repos.
• All sensitive configuration is encrypted into the token issued by the secure endpoint.
• Domain is the only client-side configuration required for rendering.
• Tokens are issued from a trusted server endpoint and delivered to the client at render time.