# Authentication Cherry signs the user in before your app loads and gives it a **launch token**: a short-lived JWT, signed by Cherry, that says who the user is and which app and room they opened. Your backend verifies it and starts its own session. The user never sees a login screen, a connect button or a signature request. ## How the token arrives 1. The user taps your app. On their first launch Cherry shows a one-time screen with your app's operator, the data it receives and links to your terms. 2. Cherry loads your URL and sends the token to the SDK over the host bridge (never in the URL). 3. `useCherryMiniApp()` (React) or `cherry.launchToken` (core client) exposes it, together with the user and room. 4. Your frontend sends it to your backend once, which verifies it and returns your own session. ## Claims | Claim | Type | Meaning | | --- | --- | --- | | `iss` | string | Always `https://chat.cherry.fun` | | `aud` | string | Your app ID. Reject tokens for any other app. | | `app_id` | string | Your app ID (same as `aud`, kept for older verifiers) | | `sub` | string | The user's wallet address on Solana. It changes when the person picks another wallet to pay with. | | `cherry_id` | string, optional | The user's stable Cherry account ID. Key your users by it. | | `payment_wallet` | string, optional | The wallet the user pays from, when it differs from `sub` | | `user` | object | `display_name`, `avatar_url` | | `room_id`, `room` | string, object | Where the app was opened: id, `title`, `member_count` | | `permissions` | string[] | Bridge capabilities granted to this launch | | `tier` | string | Your app's trust tier: `unverified`, `verified` or `partner` | | `iat`, `exp`, `jti` | number, number, string | Issued at, expiry (5 minutes), unique id | Only what is inside the verified token is trustworthy. Query parameters and anything posted over the bridge are not signed: never use them to decide who the user is or how much money moves. ## Verify it Every verifier must check the RS256 signature against Cherry's keys and the issuer, audience, expiry and app id. On a JavaScript backend, use the SDK: ```ts // Node, Bun, Deno, edge runtimes import { verifyLaunchToken } from '@cherrydotfun/miniapp-sdk'; const claims = await verifyLaunchToken(token, { appId: APP_ID }); const userId = claims.cherry_id ?? claims.sub; // Failures throw LaunchTokenError with a code: TOKEN_EXPIRED, ISSUER_MISMATCH, // AUDIENCE_MISMATCH, APP_ID_MISMATCH, JWKS_UNAVAILABLE… ``` ```ts // Or with jose directly import { createRemoteJWKSet, jwtVerify } from 'jose'; const JWKS = createRemoteJWKSet(new URL('https://chat.cherry.fun/.well-known/jwks.json')); const { payload } = await jwtVerify(token, JWKS, { issuer: 'https://chat.cherry.fun', audience: APP_ID }); if (payload.app_id !== APP_ID) throw new Error('token is for another app'); ``` ```python # Python: PyJWT import jwt jwks = jwt.PyJWKClient("https://chat.cherry.fun/.well-known/jwks.json") key = jwks.get_signing_key_from_jwt(token).key claims = jwt.decode(token, key, algorithms=["RS256"], audience=APP_ID, issuer="https://chat.cherry.fun") assert claims["app_id"] == APP_ID ``` ```go // Go: github.com/MicahParks/keyfunc/v3 + github.com/golang-jwt/jwt/v5 k, _ := keyfunc.NewDefault([]string{"https://chat.cherry.fun/.well-known/jwks.json"}) tok, err := jwt.Parse(raw, k.Keyfunc, jwt.WithValidMethods([]string{"RS256"}), jwt.WithIssuer("https://chat.cherry.fun"), jwt.WithAudience(appID), ) ``` ## Sessions - **Key users by Cherry ID.** Store users under `cherry_id ?? sub`. `sub` is a wallet: the same person gets a new `sub` when they pick another wallet to pay with. - **Exchange once.** The token expires after five minutes and its `jti` is unique: create your own session right away and keep it in memory. - **No cookies across frames.** Inside Cherry your app is framed, and browsers drop third-party cookies. Send your session in an `Authorization` header. - **Wallet switches.** If the user switches wallets inside Cherry, the SDK receives a new token. Treat it as a new sign-in for the same user: `cherry_id` stays, `sub` changes. - **Outside Cherry.** `isReady` never becomes true with a launch token when the app runs in a normal browser tab. Keep your usual login there. > **Note:** Apps without a backend can render from the SDK's `user` object, but must not move funds or grant anything based on it alone. Anything that matters belongs behind a verified token.