PlanewardPlaneward Docs
PlanewardPlaneward Docs
Welcome

Developers

REST APIAuthenticationWebhooksMCPEmbedded projectsTask description contentDeveloper hub
Community appsQuickstartIdentity tokenAPI accessApp webhooksTesting your apppostMessage protocol

API

Community apps

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

ClaimTypeValue
issstringhttps://app.planeward.com
audstringYour app id
substringCommunity membership id (member) or workspace membership id (staff)
iat, expnumberIssued at, expiry (seconds)
workspaceIdstringInstalling workspace
installationIdstringInstallation; send it as x-planeward-installation in API calls
channelIdstring | nullSet when view is experience
view"experience" | "dashboard"Member channel or staff dashboard
role"member" | "admin"Viewer role
namestringDisplay name
avatarstring | nullAvatar 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 aud equals 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.

Quickstart

A Next.js community app that greets the viewer by name.

API access

Call Planeward from your app's backend with the app secret.

On this page

ClaimsExpiryVerify with the SDKVerify without the SDKRules