Embed troubleshooting

Common Jupid Embed integration problems.

Start by identifying where the flow stops: the host token request, the Jupid bootstrap, /api/embed/session, or the loaded workspace. Keep the partner ID, environment, browser or device version, and failing HTTP status available.

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 header has alg: HS256 and typ: JWT, and the signature uses that environment's shared secret;
• email, name, payload, iat, and jti are present with the types required by the authentication contract.

HTTP 401 means authentication failed. HTTP 403 means the origin or native transport check failed: verify the browser origin allowlist in the same Jupid environment, or the native SDK's exact HTTPS appUrl and same-origin session request. Origin rejection is not fixed by signing another token.

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. The browser SDK still attempts its configured tokenUrl on that 401, defaulting to /api/jupid/embed-token.

The React Native SDK calls getToken once more and reports a second rejected JWT through onError. Other session failures can display inside the WebView without reaching that callback. Check the session response as described in the native authentication lifecycle.

Fetch a freshly signed token for authentication retries. A token remains valid until its expiry; jti is required but is not consumed as a one-time ticket.

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.

For native hosts, the SDK opens external top-level URLs in the system browser. It does not supply the provider's return-link bridge. Validate that bridge and the host's URL schemes separately; see native platform boundaries.

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 and that the partner-user mapping exists. A successful embed session creates that mapping; the partner API bootstrap can also create it before the first embed session.

The current account-change webhook acknowledges receipt before background processing finishes. If the user is unmapped when the worker runs, it skips the snapshot. Create the mapping, then send the current snapshot again. Use the webhook guide for the partner-specific payload contract.

Safari blocks the session

Some browser configurations restrict third-party iframe storage. If this affects a launch partner, inspect whether /api/embed/session succeeds but the next request loses the session. Test the supported browser configuration and report the result to slava@jupid.com.

The browser SDK currently has no top-level authorization handshake or automatic storage-access recovery. A successful token exchange alone does not prove that the browser will retain the iframe session. Native integration uses a separate top-level WebView, but is not a recovery mechanism for a browser iframe.

Still stuck

Send support the failing step, partner ID, environment, time, and error status. Exclude tokens, signing secrets, and financial payloads. After a fix, repeat the affected checks in testing and launch.