Identity token
The signed JWT that tells your app who is viewing.
The host gives your app an RS256 JWT for the current viewer. Get it with app.getToken() (see Quickstart) or the postMessage protocol.
Claims
| Claim | Type | Value |
|---|---|---|
iss | string | https://app.planeward.com |
aud | string | Your app id |
sub | string | Community membership id (member) or workspace membership id (staff) |
iat, exp | number | Issued at, expiry (seconds) |
workspaceId | string | Installing workspace |
installationId | string | Installation; send it as x-planeward-installation in API calls |
channelId | string | null | Set when view is experience |
view | "experience" | "dashboard" | Member channel or staff dashboard |
role | "member" | "admin" | Viewer role |
name | string | Display name |
avatar | string | null | Avatar URL |
For a member, sub is the memberId that member endpoints take. A staff viewer's sub is not a member id.
Expiry
Tokens expire after 5 minutes. app.getToken() caches the token and requests a new one about 30 seconds before it expires, so call it before each request to your backend instead of storing the token.
Verify with the SDK
import { verifyPlanewardToken } from "@planeward/sdk/server";
const claims = await verifyPlanewardToken(token, { appId: "your-app-id" });It throws on an invalid signature, issuer, audience or expiry. A valid token issued to a different app throws PlanewardTokenAudienceError, which usually means PLANEWARD_APP_ID points at the wrong app. Use one app per environment. baseUrl defaults to https://app.planeward.com.
Verify without the SDK
Public keys are at https://app.planeward.com/api/auth/jwks. With jose:
import { createRemoteJWKSet, jwtVerify } from "jose";
const jwks = createRemoteJWKSet(
new URL("https://app.planeward.com/api/auth/jwks")
);
const { payload } = await jwtVerify(token, jwks, {
issuer: "https://app.planeward.com",
audience: "your-app-id",
algorithms: ["RS256"],
});Rules
- Always check
audequals your app id. A token issued to another app is valid Planeward JWT, but not for you. - Don't rely on cookies inside the iframe. Browsers block third-party cookies, so your session cookie may never be sent. Send the token with each request instead.
Planeward Docs