Authentication
How partner identity is mapped into a secure embedded Jupid session.
Jupid Embed uses partner-signed JWTs. The partner authenticates the user in its own product, then its server creates a short-lived token for Jupid.
The shared secret must stay on the partner server. It must never be exposed in frontend code, browser bundles, mobile clients, or public repositories.
Required claims
The JWT must be signed with HS256 and include this protected header:
{
"alg": "HS256",
"typ": "JWT"
}{
"iss": "your-partner-id",
"aud": "jupid-embed",
"sub": "partner-user-123",
"email": "user@example.com",
"name": "Jane Founder",
"payload": {
"company_name": "Acme Studio"
},
"iat": 1779360000,
"exp": 1779360300,
"jti": "one-token-id"
}Claim rules
| Claim | Rule |
|---|---|
iss | Partner ID provided by Jupid. |
aud | Must be jupid-embed. |
sub | Durable partner user ID. This is the primary mapping key. |
email | Used when the partner-user mapping is first created. Existing mappings keep their original Jupid auth email. |
name | Display name stored on the Jupid user profile. |
payload | Partner metadata stored by Jupid. |
iat | Issued-at timestamp in seconds. |
exp | Expiration timestamp in seconds. Use roughly 5 minutes. |
jti | Unique token ID for traceability. |
Jupid maps partner users by (partner_id, external_user_id), where
external_user_id comes from sub.
Session flow
- The partner page loads
/embed.jsfrom the Jupid app URL for the current environment. - The partner page fetches a signed token from its own backend.
- The SDK creates an iframe at
JUPID_EMBED_APP_URL/embed/:partnerId. - The iframe asks the parent window for the token.
- The SDK sends the token to the iframe with
postMessage. - Jupid verifies the origin, signature, header, issuer, audience, and expiration.
- Jupid finds or creates the mapped Jupid user.
- Jupid creates a browser session and redirects the iframe.
Origin allowlist
Jupid checks the parent page origin before accepting a token. Send Jupid every local, staging, and production origin that will host the embed in its matching environment.
Example:
http://localhost:3000
https://staging.partner.com
https://app.partner.comJupid also configures iframe frame-ancestor policy for those origins.