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=%232563ebLive 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_WRITEscope - Developer hub for the in-app settings
- API reference
Planeward Docs