Partner-signed links
Create signed and encrypted onboarding tokens without calling the link-generation endpoint.
Nested token format
The link ID is a compact JWE containing a complete signed JWT. Signing proves which approved partner issued the identity claims; encryption prevents identity data from appearing in URLs, browser history, proxies, and analytics.
- Sign the claims as a compact JWT using your registered private key.
- Encrypt that entire JWT using Genesis's public encryption key.
- Put the compact JWE in
https://forum.genesistudio.com/link?id=<JWE>.
A plain JWT, base64-encoded JSON, or conventional hash of user data is not accepted.
Required algorithms
The inner JWT signature may use EdDSA, ES256, or RS256, and its protected header must include the registered signing key ID as kid.
The outer JWE protected header must use:
| Name | Required value |
|---|---|
alg | RSA-OAEP-256 |
enc | A256GCM |
cty | JWT (recommended) |
The plaintext is the complete compact signed JWT, not its decoded payload. Private signing keys never leave your server; Genesis publishes only an encryption public key to partners.
JWT claims
{
"iss": "penguin-squad",
"aud": "genesis-forums",
"sub": "stable-external-user-uuid",
"jti": "unique-random-single-use-id",
"iat": 1785200000,
"nbf": 1785200000,
"exp": 1785200600,
"username": "reader123",
"email": "reader@example.com",
"destination": "/novels/memorize/discussion"
}
| Claim | Required | Meaning |
|---|---|---|
iss | Yes | Exact integration slug |
aud | Yes | genesis-forums |
sub | Yes | Stable external UUID |
jti | Yes | Unique single-use token ID |
iat | Yes | Issued-at NumericDate |
exp | Yes | Expiry NumericDate, no more than 15 minutes after issue |
nbf | No | Not-before NumericDate |
username | No | Proposed username, at most 50 characters |
email | No | Proposed email, at most 320 characters |
destination | No | Safe internal Forum path |
Expiry, replay, and validation
Keep token lifetime at or under 15 minutes; 10 is recommended. Generate a cryptographically random jti for each link. Genesis records the token and decision so the same link cannot link twice. Do not reuse a token after an error or issue one link to multiple members.
Genesis decrypts the JWE, verifies the inner JWT against the registered partner key, validates standard and custom claims, checks replay state, validates proposed fields and destination, then displays the consent screen. Failure at any stage prevents linking.