Using embed secrets (JWTs)

​

What are Embed Secrets?

Embed secrets are a key id, key value pair that allow you to generate JWTs to embed your dashboards. The JWT Explo uses is a JWT with a JWE body. You can find more information about JWTs at this link. You would use this token the same way you use your dashboard id, customer token pair, but the token has two extra functions:

• Hides this dashboard id and customer token from your customers
• Expires at a cadence you set (default is one day)

​

Generating a JWT

​

Generate the Embed Secret

First, you must generate an embed secret. Go to the Data Visibility Groups section in the settings page, create a new secret, and copy your secret’s value and id. Then, you have two options:

​

Use Explo’s API to generate the JWT

For convenience, Explo exposes an endpoint you can use to generate a JWT for your customer/dashboard pair. You could hit this endpoint when your customer loads the page and provide the JWT immediately to your embedded component.

See here for docs on this endpoint

​

Manually generate the JWT

You can also generate the JWT yourself. The specs of the JWT are as follows

Claims:

• cst: your customer id, the one you provided to Explo
• dsh: your embed id, taken from the Explo app
• exp: the desired expiration timestamp
• kid: the key id you’re using to sign and encrypt the jwt
• alg: A256GCM

# A python example:
from jose import jwe

jwt = jwe.encrypt(
  json.dumps(
      {
          "exp": (datetime.utcnow() + timedelta(hours=2)).timestamp(),
          "cst": "customer_1",
          "dsh": "abcdef",
      }
  ),
  encryption="A256GCM",
  key=key_value,
  kid=key_id,
).decode("utf-8")

// A javascript example:
import * as jose from "jose";

const enc = new TextEncoder();
const secret = enc.encode(key_value);

const jwt = new jose.EncryptJWT({
  cst: "customer_1",
  dsh: "abcdef",
})
  .setProtectedHeader({ alg: "dir", enc: "A256GCM", kid: key_id })
  .setIssuedAt()
  .setExpirationTime("2h")
  .encrypt(secret);

​

Testing an Embedded Dashboard or Report Builder

You can use Explo’s Embed Modal to generate a JWT for testing purposes. The JWT will be generated using a test Embed Secret. Note that this JWT will expire after 24 hours, so it should not be used in production.

On the Dashboard Page or on the Report Builder Page, select the dashboard or report builder you’d like to embed and click the Embed option from its menu. Select a customer from the dropdown and the JWT will be automatically generated and inserted into the resulting code snippet.