Authentication (JWT)

Orshot Embed typically relies on Referrer Headers to ensure that your embed is only loaded on allowed domains. However, some browsers (like Safari) or privacy extensions may strip these headers, causing the embed to fail validation.

To solve this, Orshot supports JWT (JSON Web Token) authentication. By signing a token on your server and passing it to the embed, you can securely authorize access without relying on browser headers.

When to use this?#

• If you have users on Safari facing "Access Denied" errors.
• If you are embedding inside an invalid environment (e.g. some mobile webviews).
• If you want an extra layer of security beyond domain whitelisting.

Setup#

1. Generate Signing Secret#

Go to your Workspace > Embed > Authentication settings and generate a Signing Secret.

2. Sign a Token (Server-Side)#

On your backend, generate a JWT signed with this secret. The token does not require a specific payload structure currently, but we verify the signature against your secret.

Example (Node.js):

import jwt from "jsonwebtoken";

const SIGNING_SECRET = "your-signing-secret-from-dashboard";

// Generate a token (valid for 1 hour)
const token = jwt.sign(
  {
    embedId: "your-embed-id", // Optional context
    nonce: Math.random(), // Prevent replay attacks (optional)
  },
  SIGNING_SECRET,
  { expiresIn: "1h" }, // Short expiry recommended
);

const embedUrl = `https://orshot.com/embeds/YOUR_EMBED_ID?token=${token}`;

3. Pass Token to Embed#

Append the token query parameter to your embed URL.

<iframe
  src="https://orshot.com/embeds/12345?token=YOUR_GENERATED_TOKEN"
  width="100%"
  height="600"
  allow="clipboard-write"
></iframe>

Security Best Practices#

• Short Expiry: Set a short expiration time (e.g., 1h or even 5m) for your tokens. The token is only needed for the initial load.
• Backend Only: NEVER expose your Signing Secret on the client-side. Always generate the token on your server.