Troubleshooting

Common Jupid Embed integration problems.

The iframe is blocked

Check that Jupid has the exact partner origin in the iframe ancestor allowlist. Origins must include scheme, host, and port when a port is used.

http://localhost:3000
https://staging.partner.com
https://app.partner.com

The token is rejected

Confirm:

• iss is the partner ID issued by Jupid;
• aud is jupid-embed;
• sub is present and stable;
• exp is in the future;
• the token is signed with HS256 and the shared secret;
• the browser origin is allowlisted in the same Jupid environment.

If Jupid returns HTTP 401, the current SDK retries once by fetching a new token from tokenUrl. If the partner page passes token directly and has no token endpoint available to the SDK, the partner page must fetch a newly signed token and remount Jupid. Do not retry the same token.

Users are duplicated

Use the same durable partner user ID in sub for every request. Do not use email as the primary mapping key if users can change email addresses.

The embed has no height

The iframe fills its container. Give the host workspace and embed container a real height.

#jupid-embed {
  height: 100%;
  min-height: 720px;
}

Bank or payment popups fail

Remove host iframe sandboxing first. Provider popups and external redirects are easier to validate without sandbox restrictions.

Webhooks return 401

Confirm the request includes x-jupid-signature and that it is a hex HMAC-SHA256 digest over the exact raw request body. Signing formatted JSON and sending minified JSON, or the reverse, changes the digest.

Webhooks are accepted but nothing changes

Confirm the webhook sub is the same durable user ID used in the embed JWT. Jupid can process account-change webhooks only after the user has opened the embed at least once and Jupid has created the partner-user mapping.

Safari blocks the session

Some browser configurations restrict third-party iframe storage. If this affects a launch partner, contact slava@jupid.com so Jupid can enable a top-level authorization handshake for that partner.