SDK backend | Kittl SDK Documentation
@kittl/sdk-backend handles authentication on your server by verifying short-lived JWTs from Kittl users, keeping sensitive auth logic out of the browser sandbox. It gives you a `KittlSDK` class to validate tokens and optional external key storage for serverless/edge environments.
- Frontend calls `kittl.auth.getUserToken()` to get a JWT, sends it to your backend, where `KittlSDK.verifyUserToken()` validates it before processing the request
- Token verification returns `payload.sub`, a pseudonymous per-app user ID that stays consistent for each user across sessions
- External signing key caching is required for serverless, edge, and autoscaling runtimes where in-memory caches don't persist between requests
@kittl/sdk-backend is the server-side half of Kittl's authentication system. While @kittl/sdk runs in your browser sandbox, this backend package handles the security-sensitive parts: verifying JWTs from users, managing signing keys, and handling auth errors. You install it with pnpm, import KittlSDK and TokenInvalidError, then use it to validate tokens before processing requests on your server.
The actual flow is straightforward. Your frontend calls kittl.auth.getUserToken() to grab a short-lived JWT for the authenticated user, then sends it along with whatever request needs authorization. Your backend receives it and runs verifyUserToken() to check the token's validity. If it passes, you get back a payload with a pseudonymous user ID (payload.sub) that stays consistent per app—useful for tracking users without exposing their real identity.
One practical detail matters here: if you're running on edge functions, serverless, or autoscaling infrastructure, in-memory caching won't survive between requests. You'll need to pass a signingKeyCache adapter to persist signing keys across cold starts. Otherwise you're constantly re-fetching them. Also, make sure you're passing your actual Kittl app ID as the appId parameter—it's used as the JWT audience, so mismatching it will cause verification to fail.