Core Concepts

The General Wisdom platform issues RS256-signed JWTs when a user launches an OSINT session through the marketplace. This token represents an authorized session and contains the claims needed for the provider application to identify the user, organization, and session parameters.

Token Delivery

The JWT is passed to the provider application via a URL query parameter:

https://your-app.com/?gwSession=<JWT>

The SDK extracts this token automatically during sdk.initialize(). If the token is not present in the URL, the SDK falls back to sessionStorage (to survive OAuth redirects within the provider app).

Claims

Claim	Type	Description
sessionId	string	Unique session identifier
applicationId	string	Provider application ID
userId	string	User who launched the session
orgId	string	Organization that owns the session
email	string	User's email address
startTime	number	Unix epoch seconds when session started
durationMinutes	number	Session duration in minutes
exp	number	JWT expiration (Unix epoch seconds)
iat	number	JWT issued-at (Unix epoch seconds)
iss	string	Issuer (generalwisdom.com)
sub	string	Subject (same as userId)

Signing

• Algorithm: RS256 (RSA Signature with SHA-256)
• Key type: RSA 2048-bit minimum
• Key rotation: Keys are rotated periodically; always fetch the current key set from the JWKS endpoint

Verification

JWKS (Default)

The SDK verifies the JWT signature by fetching the public key from the platform's JWKS endpoint:

https://api.{env}.generalwisdom.com/.well-known/jwks.json

Environment	JWKS Endpoint
Development	https://api.dev.generalwisdom.com/.well-known/jwks.json
Demo	https://api.demo.generalwisdom.com/.well-known/jwks.json
Production	https://api.generalwisdom.com/.well-known/jwks.json

The SDK matches the kid (Key ID) header in the JWT to the corresponding key in the JWKS response, then verifies the RS256 signature.

Backend Validation (Alternative)

For sensitive applications, the SDK supports server-side validation via:

POST /sdk/sessions/validate

Enable with useBackendValidation: true in the SDK config. The platform backend performs full validation including session status checks and returns the decoded claims.

Lifecycle

• One JWT per session. Each marketplace session launch produces a single JWT.
• Not refreshable. The token cannot be renewed. When the session is extended via the SDK, the server updates the session record but does not issue a new JWT. The SDK timer syncs with the server via heartbeats.
• Expiration matches the session. The exp claim corresponds to the session's original end time. Extensions are tracked server-side.

Security

• Never send to third parties. The JWT contains user identity information and session authorization. Do not forward it to external services.
• Never log the full token. Log only the sessionId claim for debugging.
• Store in sessionStorage only. The SDK stores the token in sessionStorage (not localStorage) so it is scoped to the browser tab and cleared when the tab closes.
• Validate before trusting. Always verify the signature and check exp, iss, and applicationId claims before granting access.

Example Token

{
  "sessionId": "35iiYDoY1fSwSpYX22H8GP7x61o",
  "applicationId": "your-app-id",
  "userId": "a47884c8-50d1-7040-2de8-b7801699643c",
  "orgId": "org-123",
  "email": "user@example.com",
  "startTime": 1763599337,
  "durationMinutes": 60,
  "exp": 1763602937,
  "iat": 1763599337,
  "iss": "generalwisdom.com",
  "sub": "a47884c8-50d1-7040-2de8-b7801699643c"
}

Session Lifecycle Overview

1. URL Detection    → SDK checks for gwSession query parameter
2. JWT Validation   → Verify signature, expiration, claims
3. onSessionStart   → Your hook provisions the user
4. Timer Start      → Countdown begins
5. Session Active   → User interacts with your app
6. Warning          → Alert at configurable threshold (default: 5 min remaining)
7. onSessionEnd     → Your hook cleans up
8. Redirect         → Return to marketplace (optional)