Partner-generated signed links

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.

1. Sign the claims as a compact JWT using your registered private key.
2. Encrypt that entire JWT using Genesis's public encryption key.
3. 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. A hash cannot securely carry recoverable claims or prove freshness by itself.

Required algorithms

The inner JWT signature may use EdDSA, ES256, or RS256. Its protected header must include the registered signing key ID as kid.

The outer JWE must use:

• Key management: RSA-OAEP-256
• Content encryption: A256GCM
• Recipient: the Genesis public encryption key supplied for the environment

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"
}

iss must exactly equal your integration slug. aud must be genesis-forums. sub, jti, iat, and exp are required. username, email, destination, and nbf are optional.

Expiry and replay protection

The token may live for at most 15 minutes; 10 minutes is recommended. Generate a cryptographically random jti for each link. Genesis records the token and decision so the same link cannot link twice.

Clock skew should be small and server clocks should use a reliable time source. Do not reuse a token after an error or issue one link to multiple members.