PlanewardPlaneward Docs
PlanewardPlaneward Docs
Welcome

Developers

REST APIAuthenticationWebhooksMCPEmbedded projectsTask description contentDeveloper hub

API

Embedded projects

Secure iframe embed so host-site users can create and manage their own partitioned projects.

Host sites embed Planeward projects in an iframe. Your backend mints a short-lived session for each of your users. Inside the iframe they only see projects they created.

Enable the embed and allow-list origins in the workspace Developer → Embed page. Create an API key with the EMBED_WRITE scope.

Mint a session

Call this from your server only. Never put the API key in the browser.

POST /api/v1/embed/sessions
x-api-key: wbk_...
Content-Type: application/json

{
  "externalUserId": "user_123",
  "displayName": "Ada Lovelace",
  "email": "[email protected]"
}
{
  "data": {
    "token": "…",
    "embedUrl": "https://app.planeward.com/embed/session?token=…",
    "expiresAt": "2026-09-02T01:30:00.000Z"
  }
}

externalUserId is your user id. Planeward upserts an embed user per workspace and partitions projects by that id.

Sessions last one hour. Tokens are stored as SHA-256 hashes.

Create a task for a user

The same EMBED_WRITE key can list that user's projects, including the status ids task creation needs. An unknown externalUserId returns an empty list and embedUser: null.

GET /api/v1/embed/projects?externalUserId=user_123
x-api-key: wbk_...
{
  "data": [
    {
      "id": "proj_123",
      "name": "Client work",
      "description": null,
      "statuses": [
        {
          "id": "status_backlog",
          "name": "Backlog",
          "type": "TODO",
          "rank": "1000"
        }
      ]
    }
  ],
  "embedUser": {
    "id": "eu_123",
    "externalUserId": "user_123",
    "displayName": "Ada Lovelace",
    "email": "[email protected]"
  },
  "meta": { "total": 1, "limit": 50, "offset": 0 }
}

Create the task with TASKS_WRITE on the project and status from that response:

POST /api/v1/projects/proj_123/tasks
x-api-key: wbk_...
Content-Type: application/json

{
  "title": "Follow up from the client meeting",
  "statusId": "status_backlog"
}

Iframe

<iframe
  src="EMBED_URL_FROM_RESPONSE"
  style="width: 100%; height: 720px; border: 0"
></iframe>

The session URL sets an HttpOnly; Secure; SameSite=None; Partitioned cookie, then redirects to /embed/projects.

Allowed origins

The iframe only loads when frame-ancestors matches an origin you listed. An empty list refuses to render. Use full origins, one per line — https://app.example.com.

What users can do

  • Create their own projects and rename them in Settings
  • Board and list views
  • Create, edit, move, and delete tasks
  • Live updates over the same realtime channels as the main app

They cannot open other embed users' projects, workspace settings, CRM, or chats.

Theming

Defaults come from Developer → Embed:

  • Theme: light, dark, or auto
  • Accent color and corner radius
  • Optional logo URL and hide-Planeward branding

Per-load overrides on the iframe URL:

/embed/session?token=…&theme=dark&accent=%232563eb

Live updates from the host page. The embed checks event.origin against your allowed origins:

iframe.contentWindow.postMessage(
  { type: "planeward:set-theme", theme: "dark", accent: "#2563eb" },
  "https://app.planeward.com"
);

Security model

  • API keys stay on the host backend
  • Short-lived tokens, hashed at rest
  • Partitioned third-party cookie after the first load
  • Per-workspace frame-ancestors
  • Every embed query and mutation filters on embedUserId
  • Realtime subscriptions are limited to that user's project and task channels

Next

  • Authentication for the EMBED_WRITE scope
  • Developer hub for the in-app settings
  • API reference

MCP

Streamable HTTP MCP for Claude, ChatGPT, editors, and any MCP client.

Task description content

Stored Plate JSON contract — canonical field, allowed nodes, security, and write rules.

On this page

Mint a sessionCreate a task for a userIframeAllowed originsWhat users can doThemingSecurity modelNext