```
With `record=":slug"` the last URL segment is the match value:
`/products` → no route segment at all, so nothing resolves → empty branch = overview
(this needs `route_mandatory: false`; with `true` the bare URL is a 404),
`/products/kliklijsten` → slug `kliklijsten` (match branch).
#### Dynamic Filter Tokens
The nested list can inject a value from the **parent / the URL** into its
`filter` via a server-side token. Tokens are resolved before the filter is
parsed — outside the template engine — so they are safe to use in `filter`
attributes (`{{...}}` braces are **not**, see below).
| Token | Resolves to | Notes |
|---|---|---|
| `$route.slug` | last URL segment | request-stable — **preferred** |
| `$route.N` | N-th URL segment (0-based) | request-stable |
| `$parent.` | field from the router-matched record | generic, but **currently unreliable** inside a nested loop (the matched record may be `null` while the inner loop runs) — prefer `$route.slug` |
```html
filter="status:active;category_slug:$route.slug"
```
Unresolvable tokens fall back to `''` → the row simply doesn't match (safe
failure mode). No `$` token present → no-op.
**Hard rules (why no Handlebars in a filter):**
- **Never put `{{...}}` in a `filter` attribute.** `{{id}}` resolves empty in
the nested scope; `{{../id}}` and `{{#if}}` get processed by the engine and
corrupt the SSR comment delimiters → the empty branch leaks into the output.
Use `$route.` / `$parent.` tokens instead of braces.
- **Never wrap an SSR loop in `{{#if}}`.** Same reason. Use the native
match/empty branch split shown above.
**Prerequisite — filterable field must be top-level.** Filters only match
top-level keys. To filter products on category slug, the catalog normalizer must
expose `category_slug` top-level on each product (it does for `source=catalog`).
A field that only exists nested (e.g. `category.slug`) is not filterable.
#### Per-Record SEO — `
```
**Attributes** (on the open tag): `source` / `entity` / `match` work as in `wps-mapi`
(the tag is self-describing — it does not inherit route context). `record` accepts
`:slug` (last URL segment), `:N` (N-th segment), or a literal value.
`title` and `description` go **as attributes** and may contain template tokens.
> **⚠️ Always write `match=` explicitly on `wps-seo`.** Unlike the route and the
> body SSR block, which default to `slug`, this tag defaults to **`id`**. On a
> slug-routed page, omitting `match="slug"` makes the lookup miss, the block is
> dropped silently, and the page falls back to page-level SEO — no error, no log
> line. Every record then shares one title, which is exactly the duplicate-title
> problem this tag exists to solve.
**Critical rule — title/description are ATTRIBUTES, never elements.** Do not put a
`` or description `<meta>` element inside the block: the platform strips the
first `<title>` unconditionally during SEO processing, so an inline element gets
clobbered before your override runs. Attributes for title/description; all other
head-HTML (OG, JSON-LD) goes in the block body.
**Behavior:**
- No `<!--#wps-seo` tag on the page → output is byte-identical (safe everywhere)
- Strips the page-level duplicates it overrides (title, description, og:title,
og:description) and places the per-record versions authoritatively in `<head>`
- Record not found → the block disappears; the page falls back to page-level SEO
**Caveats:**
- The template engine HTML-escapes `{{ }}` — JSON-LD string values containing `&` or
`"` come out entity-encoded (valid JSON, cosmetically off). Keep JSON-LD fields to
safe data: name, sku, image URL.
- Price/`offers` in JSON-LD is deliberately **not** included by default — whether
prices appear in Google (incl./excl. VAT, variable pricing) is the site owner's call.
- Test SSR on the `*.websitepublisher.ai` **preview domain** — an uninitialized
placeholder page on a custom domain may serve fallback content instead of the
SSR pipeline.
#### SSR Wrapper Attributes
The SSR injector adds `data-mapi-ssr` attributes to rendered blocks:
```html
<div data-mapi-ssr="products" data-mapi-count="12">
<!-- rendered product cards -->
</div>
```
JavaScript can use these to enhance SSR-rendered content (e.g. add client-side
search/filter on top of the server-rendered list). SSR and JS coexist naturally.
**CSS gotcha (always needed for an SSR list inside grid/flex).** Each SSR loop
renders inside its `<div data-mapi-ssr="…">` wrapper. A grid/flex container
around the loop then has only **one** child → one column. Fix:
```css
[data-mapi-ssr] { display: contents; }
```
That works anywhere. When the grid is yours to define, `wrap-class` is cleaner —
the SSR wrapper *becomes* the grid, so there is no extra element and no CSS rule:
```html
<div class="page-wrap">
<!--#wps-mapi entity="blogpost" filter="status:published" wrap-class="card-grid" -->
<a class="card" href="/blog/{{slug}}">{{title}}</a>
<!--#wps-mapi-empty -->
<p>Nothing published yet.</p>
<!--#/wps-mapi -->
</div>
```
Note the empty branch is **not** wrapped, so it never inherits `card-grid`.
> **⚠️ You will not see this bug with one record.** A broken grid holding a single
> card looks identical to a working one. It only reveals itself when the second
> record arrives — often days later, on a page you thought was finished. Test
> grid layouts with at least two records.
**Table gotcha (`wrap="tbody"` is mandatory inside a `<table>`).** The default
wrapper is a `<div>`, which is not valid inside a table. The browser hoists it out
of the table, the rows land outside their parent, and DOMPDF aborts the render with:
```
Min/max width is undefined for table rows
```
That message names neither the table nor `wps-mapi`, so it is easy to spend an hour
in the wrong place. Always set the wrapper explicitly:
```html
<table>
<thead><tr><th>Product</th><th>Stock</th></tr></thead>
<!--#wps-mapi entity="products" sort="name:asc" wrap="tbody" -->
<tr><td>{{name}}</td><td>{{stock}}</td></tr>
<!--#wps-mapi-empty -->
<tr><td colspan="2">No products.</td></tr>
<!--#/wps-mapi -->
</table>
```
**These tags are HTML comments, not elements.** Writing `<wps-mapi entity="…">` as an
element silently fails to match: the block is never processed, the `{{placeholders}}`
stay in the output as literal text, and inside a table you land on the DOMPDF error
above. The opening tag is `<!--#wps-mapi … -->`, the closing tag is `<!--#/wps-mapi -->`.
#### Complete Examples
**Product grid (webshop):**
```html
<!--#wps-mapi entity="products" sort="name:asc" filter="active:1" -->
<div class="product-card {{#if featured}}featured{{/if}}">
<a href="/products/{{slug}}">
<img src="{{image | default:https://placehold.co/400x300}}" alt="{{name}}">
<h3>{{name}}</h3>
<p>{{description | truncate:100}}</p>
{{#if sale_price}}
<span class="original">{{price | multiply:0.01 | currency:EUR}}</span>
<span class="sale">{{sale_price | multiply:0.01 | currency:EUR}}</span>
{{#else}}
<span class="price">{{price | multiply:0.01 | currency:EUR}}</span>
{{/if}}
</a>
</div>
<!--#/wps-mapi -->
```
**Blog post list:**
```html
<!--#wps-mapi entity="posts" sort="published_at:desc" limit="10" filter="status:published" -->
<article>
<time>{{published_at | date:d M Y}}</time>
<h2><a href="/blog/{{slug}}">{{title}}</a></h2>
<p>{{content | striptags | truncate:200}}</p>
{{#if author}}<span>By {{author}}</span>{{/if}}
</article>
<!--#/wps-mapi -->
```
**Team page:**
```html
<!--#wps-mapi entity="team" sort="sort_order:asc" -->
<div class="team-member">
<img src="{{photo | default:https://placehold.co/300x300}}" alt="{{name}}">
<h3>{{name}}</h3>
<p class="role">{{role}}</p>
{{#if bio}}<p>{{bio | truncate:200}}</p>{{/if}}
</div>
<!--#/wps-mapi -->
```
### When to use SSR vs JavaScript vs Static HTML
| Scenario | Use | Why |
|---|---|---|
| Product catalog (10+ items, public) | **SSR** | SEO, owner adds products via admin |
| Blog, portfolio grid, FAQ (growing) | **SSR** | SEO, content changes independently |
| 3 services on about page | **Static HTML** | Too few items, rarely changes |
| 4 team members, small company | **Static HTML** | AI updates faster than building MAPI+SSR |
| Client-side search/filter | **JS** | User interaction required |
| Live price updates, stock status | **JS** | Real-time data needed |
| Shopping cart, wishlist | **JS** | User-specific state |
| Product list WITH search bar | **SSR + JS** | SSR for initial load + SEO, JS for interaction |
| Admin dashboard tables | **JS only** | No SEO needed, always behind login |
| Anything behind a visitor or member login | **JS only** | SSR is public-only and its cache is shared per page — it can never render gated data |
**Decision flow:**
1. Will Google need to index this content? → Consider SSR
2. Will the content grow beyond 10 items? → Consider MAPI entity
3. Does the owner need to update without AI? → MAPI + admin panel
4. Is it ≤5 fixed items on one page? → **Static HTML is fine**
5. Does the user interact with it? → Add JS (on top of SSR if SEO matters)
SSR and JS can coexist — use SSR for the initial server-rendered content and JS
for interactive enhancement on top.
### Translate-Safe JavaScript
Visitors often run browser auto-translate (Google Translate, Edge, Safari). It rewrites
the live DOM *after* render — splitting text nodes, wrapping them in `<font>`, and
replacing visible text. JavaScript that reads visible text back, or that a framework
mutates around a translated node, then breaks. The platform auto-injects a small guard
into every served page's `<head>` that neutralises the worst case (framework
`removeChild`/`insertBefore` crashes), but the guard **cannot** fix logic that *reads*
translated text. Write JS that never depends on rendered text:
1. **Never read visible text for logic or clipboard.** Read from JS state, `data-*`
attributes, or input `.value` / hidden inputs — none of these are translated.
2. **Copy buttons copy from the source string** you already hold in state, not from an
element's `textContent`.
3. **Branch on data, not on what a label reads** (API values, `data-*`, input values).
4. **Locate elements by class/id selectors, not by text.** Selectors survive
translation; text does not.
5. **Keep `<html lang>` accurate** (it drives the translate offer — that is correct).
**Never** add a page-wide `<meta name="google" content="notranslate">` to "fix"
translation; that just disables a feature visitors want. Use `translate="no"` only on
a specific element whose text must stay verbatim (a code snippet to copy, an API key,
an order ID).
```html
<!-- DON'T: logic depends on rendered (translatable) text -->
<span id="plan">Agency</span>
<script>
if (document.getElementById('plan').textContent === 'Agency') unlockTeam(); // breaks when translated
copyBtn.onclick = () => navigator.clipboard.writeText(promptEl.textContent); // copies the translation
</script>
<!-- DO: logic reads untranslated state / attributes -->
<span id="plan" data-plan="agency">Agency</span>
<script>
const PROMPT = 'Build me a landing page...'; // source string in state
if (planEl.dataset.plan === 'agency') unlockTeam(); // reads data-*, never the text
copyBtn.onclick = () => navigator.clipboard.writeText(PROMPT); // copies from state
</script>
```
**SSR is inherently translate-safe** — when data is rendered server-side and logic runs
off the data (not the rendered text), translation cannot break it. Prefer SSR (above);
reach for client JS only when you truly need interactivity, and then follow the rules
above.
### Data Access Control — `public_read` vs `policy_json`
Two different switches control who can touch entity data. Confusing them creates
real data leaks — this exact mistake has exposed full customer databases in the wild.
**`public_read` is a VISIBILITY flag, not a security control.**
Setting `public_read: true` only enables anonymous read via
`/mapi/public/{projectId}/{entity}`. It does **not** protect the entity and does
**not** restrict writes. It has exactly one job: making public-site content
(menus, team, services, blog posts) readable without auth.
**`policy_json` is the access control.** An entity is access-controlled **only if
it carries an explicit `policy_json`** (set via `entities(operation: "update",
entity_name: ..., policy_json: {...})`). The policy defines per-action rules and
an `owner_field` for row-level scoping.
Rules that follow from this:
- **Sensitive data (customers, orders, loyalty accounts, anything with PII or
money) must NEVER rely on `public_read` for protection.** Give those entities a
`policy_json`, or keep `public_read: false` and access them only via owner-level
calls or a dedicated integration.
- **Visitor-scoped entities** (each logged-in visitor sees/edits only their OWN
rows) need two things: a `policy_json` on the entity **and** a real owner column
(e.g. `owner_email`) that exists as an actual entity property. The policy's
`owner_field` must map to a real column — the engine fails closed otherwise.
- **A denied write surfaces as HTTP `404 Not found` — not `403`.** This is by
design (no existence leak). If a legitimate-looking write returns 404, check the
caller identity and the entity policy first, not the record.
- **Admin panels need no extra wiring.** The platform data-grid and `wsa_` admin
sessions run with owner authority over the site — admin CRUD works on
policy-protected entities automatically.
- **But owner access does not test the policy.** Because an owner session has
authority over everything, it never performs the row-ownership check at all —
so a policy with a misspelled or non-existent `owner_field` still returns every
row when you check it as the owner, and only breaks once a real logged-in
visitor loads the page. Checking a policy as the owner proves only that it is
active, never that it scopes correctly. Always verify from an actual visitor
session before you tell anyone their data is protected.
- Get the exact policy shape from `get_skill(skill_name: "dev")` before setting
`policy_json` on an entity with real user data — the server validates the JSON
is well-formed, not that your rules are semantically correct.
- Access control is currently **opt-in** (only entities with an explicit
`policy_json` are enforced). Strict mode is the platform's end state — design
entities with explicit policies **now** so nothing breaks later.
**Visitor "My Account" / "My Orders" pages — supported pattern:**
The e-commerce order endpoints `list-orders` and `get-order` are callable from a
**verified SAPI visitor session**. The server scopes results to the session email
automatically: a visitor sees only their own orders, a client-supplied
`customer_email` filter is ignored, and a cross-customer `get-order` returns 404.
Build the page with the SAPI client (visitor auth section below) and call these
endpoints from the visitor session — no admin token, no custom filtering, no
workarounds. All other order endpoints (`create-order`, `update-status`,
`get-order-by-payment`, line-meta) remain owner-only.
**Shared gated content — supported pattern.**
A page where several named members read the *same* protected records — a team wiki, an
internal project log, shared documentation — uses the `records` integration with a
`policy_json` carrying `owner_scope: "tenant"`. The policy decides which rows each member
sees and which fields are stripped; the browser never sends an identity. See
*Shared Member Content* below for the policy shape, the browser call and the guards.
Two rules that matter more here than anywhere else:
- **Never reach for `public_read: true` to make a member page "work".** The content becomes
readable at `/mapi/public/{projectId}/{entity}` by anyone with the URL, and a login gate
in the page protects nothing — it runs in the browser, and `curl` never sees it.
- **Never render it with SSR.** The render cache is shared per page, not per session.
If the content genuinely cannot be modelled this way, `gated-files` remains available for
file delivery: private storage, entitlement checked live, instant revocation — downloads
rather than browsable content.
---
## Contact Forms (SAPI) — Critical Pattern
**Always follow this exact pattern.** Deviating from it will cause "no valid session" errors,
especially on Safari and custom domains where third-party cookies are blocked.
### Step 1 — Configure the form (server-side, via MCP tool)
```
configure_form(
project_id: 12345,
form_name: "contact",
required_fields: ["name", "email", "message"],
action: {
type: "iapi",
service: "resend",
endpoint: "send-email",
input_template: {
from: "noreply@websitepublisher.ai",
to: "owner@example.com",
subject: "New contact from {{fields.name}}",
html: "<p>From: {{fields.name}} ({{fields.email}})</p><p>{{fields.message}}</p>"
}
},
max_submits_per_session: 5
)
```
### Step 2 — Add the CDN script + form handler to the page
**Always use the CDN library.** Do not write inline session management code.
The library handles sessions, CSRF tokens, stale session recovery, and all headers automatically.
> ⚠️ **`WP.sapi()` covers visitor sessions *and* signed-in tenant members.** For a
> member portal, hand the client the `wst_` token once per page load with
> `setBearer()` and keep using `call()` / `callUpload()` — see **Calling SAPI as a
> signed-in member** under Tenant-Protected Pages.
>
> The one exception is **admin authentication**. Admin login and admin-only IAPI calls
> use direct `fetch()` to `/iapi/project/{id}/admin-auth/...` with `Authorization:
> Bearer wsa_…`, because those routes carry no SAPI session at all.
```html
<script src="https://cdn.websitepublisher.ai/js/sapi-client.js"></script>
<script>
var sapi = WP.sapi(PROJECT_ID);
document.getElementById('my-form').addEventListener('submit', function(e) {
e.preventDefault();
var btn = this.querySelector('button[type="submit"]');
btn.disabled = true;
btn.textContent = 'Sending...';
sapi.submitForm('contact', {
name: document.getElementById('name').value.trim(),
email: document.getElementById('email').value.trim(),
message: document.getElementById('message').value.trim(),
website: '', // honeypot: leave empty, bots fill this in
}).then(function(r) {
if (r.ok) {
window.location.href = '/thank-you';
} else {
btn.disabled = false;
btn.textContent = 'Send';
alert(r.data.error && r.data.error.message || 'Something went wrong.');
}
});
});
</script>
```
### What the CDN library handles for you
| Feature | How |
|---|---|
| Session creation + resume | `WP.sapi(PROJECT_ID)` pre-warms on init |
| CSRF token management | Sent via `X-CSRF-Token` header + `_csrf` body (dual) |
| Session ID header | `X-Session-Id` header on every request |
| Stale session recovery | 401 response -> auto-clear -> fresh session -> retry (max 1) |
| Per-project storage keys | `wp_{projectId}_sid` -- no cross-site conflicts |
| Safari ITP compatibility | Uses sessionStorage (first-party, never blocked) |
| Auth state preservation | After successful POST, only CSRF is cleared -- session ID survives |
### Key rules -- never forget these:
| Rule | Why |
|---|---|
| Always include `website: ''` in the fields object | Honeypot field -- bots fill it in, humans leave it empty. Server silently drops the submission if non-empty |
| Never pre-fill the honeypot field | An empty string is required -- any value triggers bot detection |
| Replace `PROJECT_ID` with the actual numeric project ID | The library uses this to scope sessions and build API URLs |
### Forms with File Upload
Forms can accept image uploads from visitors via the SAPI upload endpoint.
Uploads are stored as project assets on the CDN -- no bearer token needed.
> **Building an admin panel with image upload?** See "Image Upload in Admin Panels"
> under the Admin-Protected Pages section — it shows how to combine admin auth
> with SAPI upload on the same page.
**Flow:** upload file(s) first -> collect CDN URLs -> include in form submit fields.
```javascript
var sapi = WP.sapi(PROJECT_ID);
async function uploadFile(file, onProgress) {
// The library owns the session, the CSRF token and the multipart boundary,
// picks up the replacement token this route hands back, and retries once if
// the session died server-side. Do not rebuild any of that by hand.
var res = await sapi.uploadFile('intake', file, onProgress);
if (res.ok) {
return res.data.data.asset_url; // CDN URL ready for use
}
throw new Error((res.data.error && res.data.error.message) || 'Upload failed');
}
```
`onProgress(percent, loaded, total)` is optional — pass it to drive a progress bar.
**Upload rules:**
| Rule | Value |
|---|---|
| Allowed types | JPEG, PNG, WebP only |
| Max file size | 5 MB per file |
| Max per session | 10 uploads |
| CSRF | Single-use -- library handles refresh automatically for submitForm(), manual clear needed after raw fetch upload |
| Response includes | `asset_url`, `filename`, `mime_type`, `size`, `width`, `height`, `uploads_remaining` |
**Include uploaded URLs in form submit:**
```javascript
// After uploading, pass CDN URLs as regular form fields
sapi.submitForm('intake', {
name: '...',
email: '...',
image_url_1: uploadedUrl1, // CDN URL from upload response
image_url_2: uploadedUrl2,
website: '', // honeypot
});
```
---
## Step 4 — Go Live Checklist
Before handing over to the user, verify:
- [ ] Homepage has `landingpage: true` (or was created first)
- [ ] All pages that should be findable have `seo_robots_index: true`
- [ ] All pages have `seo_title` and `seo_description`
- [ ] All `<!-- Optimizer - ... -->` comment tags are present in every page
- [ ] Multi-page sites use **fragments** for header and footer (not copy-pasted HTML)
- [ ] Repeating content uses **MAPI entities** (not hardcoded static HTML)
- [ ] Every SAPI call goes through the CDN library (`sapi-client.js`) — no inline session
code, on member pages either. A hand-written `fetch()` skips the library's stale-session
recovery, and a session that dies server-side then breaks the page **permanently**: the
visitor sees a broken page, refreshing does not help, and only clearing localStorage
fixes it. Nobody's customer knows to do that.
- [ ] Thank-you page exists if form redirects after submit
- [ ] Terms / privacy page exists if form collects personal data
- [ ] Design uses distinctive typography and cohesive color palette (not generic AI defaults)
- [ ] Design context saved via `execute_integration(service: "site_context")` for future consistency
- [ ] Website URL shared with user: `https://{subdomain}.websitepublisher.ai`
- [ ] If the user wants their own domain: hand them the two `A` records and point them at
Publish → Connect your own domain (see **Custom Domains**) — you cannot connect it
- [ ] Contact form includes `website: ''` honeypot field in the fields object
- [ ] Visual Editor session offered for image replacement and final tweaks
- [ ] **Translate-safe:** client JS reads from state / `data-*` / input values, not visible text; `<html lang>` accurate; no page-wide `notranslate` meta (framework crashes are already handled by the platform-injected guard — see **Translate-Safe JavaScript**)
### Mandatory Security Review (before going live)
A site must **not** be presented as live until this review passes. Run it as the
final gate — never skip it, even for a quick demo that the user intends to keep.
- [ ] **No secrets in client code.** No API keys, tokens, or passwords in page HTML,
inline JS, or assets. All credentials use `{{vault:...}}` references —
resolved server-side, never delivered to the browser.
- [ ] **Admin pages are auth-guarded.** Every admin/dashboard page enforces the
IAPI Admin Auth guard server-side. No admin-only data or actions reachable
without a valid `wsa_` session. No client-side-only "hidden" protection.
- [ ] **Entity exposure is intentional.** `public_read` is enabled only on entities
meant to be public. No personal data, leads, orders, or admin records exposed
via public MAPI endpoints. Remember: `public_read` is a visibility flag, not
protection — sensitive entities carry a `policy_json` or stay
`public_read: false` (see **Data Access Control**).
- [ ] **Money math is server-side.** Checkout totals, discounts, tier/volume pricing,
and loyalty points are computed and validated **by the platform integrations** —
never trusted from client-side JS, `localStorage`, or hidden form fields. A
visitor must not be able to change what they pay or what they earn by editing
the page. (Real exploits found pre-go-live: client-computed order totals and
client-written loyalty points.)
- [ ] **Admin is protected server-side.** No `showAdmin()`-style JS toggles, hidden
DOM, or devtools-bypassable checks as the only barrier — every admin page and
admin data call enforces the `wsa_` auth guard server-side.
- [ ] **No sensitive files on the public CDN.** Exports, snapshots, or data files
containing customer/order data are served through an authenticated route
(admin auth / asset proxy), never as a world-readable CDN asset.
- [ ] **Form input is validated.** Required fields set, honeypot present, file
uploads (if any) restricted to expected types/sizes via SAPI upload.
- [ ] **No customer-supplied HTML rendered unescaped.** Visitor/lead/form data shown
back on a page is escaped — no raw injection into the DOM.
- [ ] **Legal pages present where required.** Terms / privacy page exists whenever the
site collects personal data (forms, auth, leads).
If any item fails, fix it before declaring the site live. Log the outcome of this
review in TAPI (`add_task_history`) so the security gate is traceable per project.
---
## Things Only the Project Owner Can Enable
A few capabilities are switched on outside the API. There is **no MCP tool and no
endpoint** for them, so retrying with different parameters will never succeed. When you
hit one, stop and tell the user what to do.
| What | How it fails | What to tell the user |
|---|---|---|
| **Custom domain** | The site stays reachable only on `{subdomain}.websitepublisher.ai` | Dashboard → the project → **Publish** → *Connect your own domain*. See **Custom Domains** |
| **Email on a custom domain** | `email_account/list-domains` returns empty and `enable-email` refuses the domain | Only available when the domain is registered or transferred through WebsitePublisher. Otherwise: use the project's own Resend key in the vault. See **Custom Domains → Email** |
| **Invoice checkout** (B2B "pay by invoice" instead of card/iDEAL) | `checkout-flow/create-payment` with `payment_provider: "invoice"` returns **403** | The project setting `allow_invoice_checkout` is off and there is no self-service toggle yet. Email **support@websitepublisher.ai** and ask for it to be enabled on the project |
Say it plainly — "this is a setting only you can turn on, here is where" — and move on to
the rest of the build. Do not file a capability request for these: they are known, and a
request does not speed them up.
## Custom Domains — You Cannot Connect One Yourself
A project is always reachable on `https://{subdomain}.websitepublisher.ai`. Connecting a
customer's own domain is a **dashboard action performed by the project owner**. There is
no MCP tool and no AI-callable endpoint for it. Your job is to hand the owner the right
DNS record and tell them where to click.
### The DNS records
Two `A` records, both pointing at the platform load balancer:
| Type | Name / Host | Value | TTL |
|---|---|---|---|
| `A` | `@` | `206.189.242.68` | `3600` (or Auto) |
| `A` | `www` | `206.189.242.68` | `3600` (or Auto) |
That is the whole setup — the same record twice, once for the root and once for `www`.
The platform routes on the requested hostname, so both land on the right project once the
domain is saved in the dashboard.
For a subdomain instead of the root (`shop.example.com`), use one `A` record with the
subdomain label as the host — `shop` — and the same value.
Delete any other `A`, `AAAA` or `CNAME` record on those same names. Two conflicting
records for one host is the most common reason a domain keeps serving the old site.
### The owner's steps
1. Dashboard → the project → **Publish** → *Connect your own domain*
2. Enter the domain; the dashboard shows the exact record with copy buttons
3. Create that record at the DNS provider
4. **Validate & Save** in the dashboard
SSL is then auto-provisioned via Let's Encrypt. Connecting a custom domain is a **paid
plan feature**; on a plan that does not allow it the dashboard returns an upgrade prompt.
### Before pointing DNS at us
If the domain currently points at another website platform, those records must be
**replaced, not supplemented** — and the domain usually has to be released on that
platform too, or it keeps answering for it. Leftover verification records from a previous
provider are harmless but do nothing here.
### Email on a custom domain
Email is only offered when the domain is **registered or transferred through
WebsitePublisher**. On a domain we do not administer we cannot guarantee SPF, DKIM and
DMARC alignment, so we do not send on its behalf — `email_account/list-domains` will not
list it and `enable-email` will refuse. That is by design, not a bug.
For transactional mail (OTP, order confirmations) from such a domain, the two working
options are: transfer the domain to WebsitePublisher, or configure the project's own
Resend key in the vault and send through that. The second also gives the owner their own
delivery dashboard.
## Platform Knowledge
### What WebsitePublisher handles automatically
| Feature | How it works |
|---|---|
| **Sitemap** | Auto-generated. Pages appear when `seo_robots_index: true` |
| **robots.txt** | Auto-generated with "Allow all" + sitemap reference |
| **SSL certificate** | Auto-provisioned via Let's Encrypt on custom domains |
| **Canonical tags** | Injected by Optimizer when comment tag is present |
| **Open Graph** | Injected by Optimizer (uses SEO title/description) |
| **Static caching** | Pages are served as static files — extremely fast |
| **CDN** | Assets served via cdn.websitepublisher.ai |
### What requires API calls
| Feature | API |
|---|---|
| Pages and content | PAPI |
| Reusable components (header, footer) | PAPI Fragments |
| Dynamic data / entities | MAPI |
| Contact forms | SAPI |
| Third-party integrations | IAPI + VAPI |
| Visual editing (browser) | WPE |
| Clone a website | WAPI clone endpoint |
---
## Built-in Integrations — Composable Building Blocks
WebsitePublisher's integrations are not a feature list — they are composable building
blocks. Every integration speaks the same interface
(`execute_integration(service, endpoint, input)`), authenticates the same way (the Vault),
and is callable from any AI on any platform via MCP. This means the AI doesn't *build* a
payment flow, an email pipeline, or a lead system — it *assembles* them from pieces that
are already wired, secured, and maintained. Generating code gives you a draft; snapping
integrations together gives you a working system.
### Don't reinvent the wheel
WebsitePublisher includes pre-built integrations for common website needs.
You do not need to build email sending, payment processing, or SMS from scratch.
Each integration is a single tool call — credentials are stored securely in the Vault,
the platform handles authentication, rate limiting, and error handling.
### Discover what's available — list it, don't guess
You never have to guess which integrations or endpoints exist. Two tools read the
**live manifest** for the current project — they are the source of truth, more current
than this document:
- `list_integrations(project_id)` — every integration, split into **configured** (vault
secrets present, ready to call now) and **available** (needs setup), each with its full
endpoint list and descriptions. A typical project already has dozens wired
(asset upload, exports, payments, email, shipping, imports, analytics, and more).
- `get_integration_schema(project_id, service)` — the exact input fields (name, required,
type, limits) for every endpoint of one integration. Call this before
`execute_integration` so you send the correct body the first time.
If a task seems to need a capability you have no tool for, run `list_integrations` **first**.
The endpoint almost always already exists. Inventing an HTTP route, guessing a hostname,
or asking the user to build an endpoint is the wrong move — the manifest already tells you
what is there and how to call it.
### Available Integrations
All of these are called the same way — `execute_integration(project_id, service, endpoint, input)` —
and `get_integration_schema(project_id, service)` gives the exact input fields per endpoint.
The **"Reach for it when"** column is the part that matters most: it is the bridge from what the
user actually says to the capability that already exists. If a request matches one of those
phrases, the answer is never "I can't do that" — it is `list_integrations` followed by the call.
**Built-in — no API key, no setup, ready on every project.**
*Content, pages & media*
| Service | What it does | Reach for it when the user says… |
|---|---|---|
| `blog` | Posts, categories, RSS feed generation | "blog", "news section", "articles", "RSS" |
| `pages` | List pages from inside a page/integration context | "which pages exist", dynamic navigation |
| `records` | Read entity records from a page context (read-only lane) | server-rendered lists without admin auth |
| `data_grid` | Drop-in editable data grid for admin panels | "table I can edit", "spreadsheet view", "CRUD screen" |
| `asset_proxy` | Upload/delete assets from a browser admin panel (no WPA key) | "upload images from the admin panel" |
| `versioning` | Asset version history + rollback | "restore the previous version", "undo that CSS change" |
| `site_context` | Store design tokens (colors, fonts, style, locale) across sessions | "keep the same style next time" |
| `site-import` | Import an existing website into the project | "move my current site over", "rebuild what I have" |
| `schema-org` | Generate/detect structured data (JSON-LD) | "rich snippets", "structured data", "SEO markup" |
| `web-scraper` | Fetch and parse an external page (robots-aware) | "pull the content from this URL" |
*Commerce — cart, checkout, order, fulfilment*
| Service | What it does | Reach for it when the user says… |
|---|---|---|
| `product-catalog` | Products, variants, categories, bulk import | "webshop", "products", "catalog" |
| `product-search` | Search, filter and autocomplete over the catalog | "search bar for products", "filters" |
| `shopping-cart` | Server-side cart: add/update/remove, price, clear | "cart", "basket" |
| `checkout-flow` | Checkout state machine incl. **invoice mode** (quote, no online payment) | "checkout", "order on account", "request a quote" |
| `order-management` | Orders, statuses, line metadata, lookup by payment | "my orders", "order status" |
| `invoice-generator` | Generate, fetch, list and credit invoices | "invoice", "credit note", "billing document" |
| `inventory-tracker` | Stock levels, increment/decrement, low-stock report | "stock", "inventory", "sold out" |
| `discount-engine` | Discount codes: create, validate, calculate, usage | "coupon", "promo code", "discount" |
| `pricing-rules` | Tiered/volume pricing per product | "bulk pricing", "customer tiers" |
| `multi-currency` | Exchange rates and price conversion | "sell in dollars too", "currency switcher" |
| `loyalty` | Points config, per-product points, balances | "loyalty points", "rewards", "savings card" |
| `wishlist` | Per-visitor wishlist | "save for later", "favourites" |
| `abandoned-cart` | Detect abandoned carts + send recovery mail | "people leave without buying" |
| `ecommerce-analytics` | Revenue, top products, funnel, AOV, customer stats | "how is the shop doing", "best sellers" |
| `shipping-rates` | Own shipping rates and rate tables | "shipping costs", "delivery fees" |
| `myparcel` | Labels, shipments and tracking via MyParcel | "print a shipping label", "track the parcel" |
| `order_events` | Event subscriptions on the order lifecycle (webhooks, chained actions) | "email the invoice automatically when paid" |
| `calendar` | Calendars, events, bookable resources (chair/table/room), availability, slots, bookings — 15 endpoints, see "Calendar & Booking" | "appointments", "reservations", "book a table", "hotel rooms", "availability" |
*Email & messaging*
| Service | What it does | Reach for it when the user says… |
|---|---|---|
| `email_archive` | **The user's own archived mail** — search, read, threads, attachments, drafts, contexts | "my inbox", "email", "newsletters", "what did X send me", "past correspondence", "did I reply to…" |
| `resend` | Transactional email (contact forms, notifications) | "send an email when someone submits" |
| `email-templates` | Named templates: render-and-send, preview, manage | "same layout for every mail" |
| `email_layout` | Branded email layout/wrapper for the project | "our house style in emails" |
| `email_account` | Real mailboxes on a custom domain (users, aliases, domains) | "info@mydomain.com", "give me an email address" |
| `linkedin` | Post text/images to a LinkedIn organisation page | "post this to LinkedIn" |
*Members, auth & access*
| Service | What it does | Reach for it when the user says… |
|---|---|---|
| `admin_auth` | Password-protected admin areas (login, reset, sessions) | "admin panel behind a login" |
| `tenant_auth` | Provisioned/paid member portal (codes, sessions, refresh) | "member area", "customer portal", "subscribers only" |
| `account` | Signed-in member reads/updates their own record | "my account page", "profile page" |
| `member-provisioning` | Map offers/purchases to member access, event log, simulation | "buying the course gives access" |
| `gated-files` | Private file delivery to members | "paid PDF", "downloads for members only" |
| `file-downloads` | Signed download tokens with stats and revocation | "expiring download link" |
| `identity` | Change the key email on an identity | "customer changed their email address" |
| `auth_keys` | Request a project API key (human-approved, vault-stored) | AI needs a key without seeing it |
*Data, documents & flows*
| Service | What it does | Reach for it when the user says… |
|---|---|---|
| `data-import` | File → schema mapping → validate → dry-run → import | "import this CSV/Excel", "migrate my data" |
| `xlsx-export` | Generate an Excel export | "export to Excel", "download as spreadsheet" |
| `pdf_document` | Branded PDF from blocks (`generate`) or your own HTML template (`render-template`) | "PDF", "printable invoice", "downloadable brochure" |
| `pdf_layout` | Reusable PDF layout config (can copy from the email layout) | "same header on every PDF" |
| `flow_framework` | Definition + instance state machines for multi-step processes | "multi-step application", "approval workflow" |
| `leads` | Store and retrieve form submissions as leads | "collect leads", "who filled in the form" |
| `lead-scoring` | Score leads, single or batch | "which leads are worth calling" |
| `comment-system` | Comments with moderation | "let visitors comment" |
| `review-system` | Product reviews + ratings with moderation | "star ratings", "customer reviews" |
| `prediction_game` | Prediction/pool games: participants, outcomes, scores | "pool", "prediction competition" |
| `oura_sync` / `strava_sync` / `oura` / `strava` | Sync personal health/activity data into the project | "pull in my Oura/Strava data" |
| `offline_sync` | Ping/sync/pull for offline-capable clients | "keep working without internet" |
| `api-proxy` | Register and proxy an external API through the platform | "call our own backend from the page" |
| `anthropic` | Claude messages from inside the project (server-side) | "the site itself should use AI" |
*Ops, debugging & platform*
| Service | What it does | Reach for it when the user says… |
|---|---|---|
| `tracer` | Live request tracing for API + page requests | "it fails and I don't know why" |
| `capability_requests` | Report a genuine platform gap — **last resort**, see "You Are the Builder" | nothing above fits and you verified it |
**Task tracking (TAPI)** is not an integration but a first-class MCP tool: `tasks(operation: …)`.
Reach for it when the user says "where were we", "continue the build", "what's left" — see
"Task Tracking (TAPI)".
**External services — available, need an API key via `setup_integration` first.**
Roughly 50 more, addressed exactly the same way once configured:
| Category | Services |
|---|---|
| Payments | `stripe`, `mollie`, `paypal` |
| Email & marketing | `mailgun`, `sendgrid`, `smtp`, `brevo`, `mailchimp`, `convertkit` |
| Messaging | `twilio`, `slack-webhook`, `discord-webhook`, `telegram` |
| Shipping | `postnl`, `sendcloud`, `shopsunited` |
| AI | `openai`, `gemini`, `mistral`, `groq`, `perplexity`, `replicate`, `elevenlabs`, `deepgram`, `stability`, `imagen` |
| Media | `unsplash`, `pexels`, `cloudinary`, `imgur`, `giphy`, `youtube`, `vimeo` |
| CRM & productivity | `hubspot`, `notion`, `linear`, `todoist`, `github`, `sentry` |
| Data & database | `airtable`, `supabase`, `contentful`, `google-places`, `openweather`, `newsapi`, `overheid-io` |
| Booking & health | `calcom`, `oura`, `strava` |
| Social | `twitter` |
> The two lists above describe what the platform ships. **`list_integrations(project_id)` remains
> the source of truth** for what is actually reachable on this project right now — some
> capabilities are account- or entitlement-scoped and only appear there. Check the tool, not
> your memory of this table.
#### Email Archive — searching the user's own mail
This one deserves its own note because it is the capability models most often miss: when a user
asks about **their own inbox, newsletters, senders or past correspondence**, that is not a job for
web search or a third-party mail connector — the platform archives and indexes their mail itself.
`search` is scoped to one archive, so `archive_id` is **required**. Always resolve it first:
```
1. execute_integration(service: "email_archive", endpoint: "list-archives", input: {})
→ pick the archive (list-archives also accepts owner_email to filter)
2. execute_integration(service: "email_archive", endpoint: "search", input: {
archive_id: 7,
query: "The Neuron",
mode: "hybrid", // keyword (default) | semantic | hybrid (best recall)
date_from: "2026-08-28",
sort: "newest",
limit: 20
})
→ metadata + snippets, no bodies
3. execute_integration(service: "email_archive", endpoint: "get-message", input: {
archive_id: 7, id: 12345
})
→ full body_plain for the messages that matter
```
Other endpoints: `get-thread` (whole conversation), `list-attachments` + download by index,
`get-stats` (counts, date range, per-folder), `set-state` (mark handled/kept/todo),
`draft-reply` (suggested reply text — never sends), and the context layer
(`context-list`, `context-get`, `context-feed`, `context-match`, `context-members`) for
LLM-ready rolling summaries of a topic.
Two behaviours worth knowing before you report "nothing found":
- Handled messages are **hidden by default** (a reply in Sent marks them handled) — pass
`include_done: true` to see everything.
- Newsletters are frequently HTML-only, so `snippet` comes back `null` with
`snippet_source: null`. That means *no plain-text body*, **not** an empty result — fetch the
message with `get-message` instead of concluding there is nothing there.
### How integrations work
1. **Setup** — Store the API key: `setup_integration(service: "resend", secrets: {"resend_api_key": "re_..."})`
2. **Use** — Call the integration: `execute_integration(service: "resend", endpoint: "send-email", input: {...})`
3. **Done** — The platform resolves credentials, validates input, proxies the request, returns the result
API keys are **never exposed** to the AI or the browser. The Vault encrypts them at rest
and the integration proxy resolves them server-side at execution time.
### Vault References — `{{vault:...}}`
> Written with `...` as placeholder throughout this document: examples containing a
> literal key-shaped reference are redacted by the platform's secret filter when this
> skill is delivered via `get_skill`. In real templates and integration inputs, write
> the actual key name — no spaces, no dots: two opening braces, `vault:your_key_name`,
> two closing braces.
The IAPI proxy resolves `{{vault:...}}` references (two opening braces, then `vault:` + your key name, then two closing braces — no spaces) server-side before making API calls.
This is the core security mechanism that keeps secrets out of AI conversations and browser code.
**Where vault references work (server-side only):**
| Context | Works? | Example |
|---|---|---|
| `execute_integration` input | ✅ | `"api_key": "{{vault:...}}"` (e.g. key `stripe_key`) |
| Scheduled tasks (AAPI) | ✅ | Vault refs in task payload resolved at execution |
| IAPI proxy calls | ✅ | Bearer token from vault |
| Browser JavaScript | ❌ | Browser cannot access vault — use admin auth (`wsa_`) instead |
| Page HTML source | ❌ | Would expose secrets to anyone viewing source |
| MCP tool responses | ❌ | VaultSanitizer strips any leaked vault values |
**Critical rule:** Never put vault keys in browser-facing code. If a browser page needs
to call an authenticated API, use the **admin auth pattern** (`wsa_` token) for data
operations and **SAPI upload** for file uploads. The vault exists for server-side
integrations only.
### When to use integrations
| User wants... | Use this |
|---|---|
| Contact form that sends email | SAPI form + Resend integration |
| Accept payments on website | Stripe or Mollie integration |
| Quote / offerte request via the cart, **no online payment** | Checkout-flow **invoice mode** (see note below) |
| SMS confirmation after booking | Twilio integration |
| Store leads from multiple forms | Built-in Lead Capture |
| Password-protected admin dashboard | Admin Auth (IAPI admin session) |
| Open member area (anyone with an email may enrol) | SAPI Visitor Auth |
| Provisioned / paid / multi-tenant member portal | Tenant Auth (IAPI) — see "Tenant-Protected Pages" |
| Private file delivery to members (ebooks, paid PDFs) | `gated-files` — see "Member File Downloads" |
| Signed-in member reads/updates their own record ("My Account") | `account` — see "Member Self-Profile" |
| Remember design choices across sessions | Site Context integration |
| Import 50-500 products at once | `bulk-upsert-products` (Product Catalog) |
| Upload images from admin panel (browser) | **Asset Proxy** (PAPI assets) or **SAPI upload** (form uploads) |
| Request a project API key securely | Auth Keys (human-approved, vault-stored) |
| Debug failing requests or slow pages | Request Tracer |
| Search their own inbox / newsletters / past mail | `email_archive` — `list-archives` then `search` |
| Summarise what a sender or newsletter covered recently | `email_archive` — `search` (mode `hybrid`) then `get-message` |
| Draft a reply to a mail they received | `email_archive` — `draft-reply` (returns text, never sends) |
| Real mailboxes on their own domain | `email_account` |
| Remember where a multi-session build stands | `tasks` (TAPI) |
> **Quote / offerte checkout (no online payment).** To let visitors request a full quote through the normal cart → checkout flow instead of paying, use the checkout-flow **invoice provider**: `initiate-checkout` → `set-customer` → `create-payment` with **`provider: "invoice"`** → `complete-checkout`. No payment is created ("op factuur"); the resulting order is created with status `pending` / `payment_status: unpaid`, and the confirmation email still fires. That order *is* the quote request (products, quantities, customer details). **Requires the project setting `allow_invoice_checkout`.** Combine with hidden prices (`price_cents: 0`) for a pure request-a-quote shop: the cart shows products + quantities only, the order total is €0, and you follow up with a real quote. Full cart/checkout wiring lives in the e-commerce cookbook.
**Always check if an integration exists before building custom solutions.**
The built-in integrations handle authentication, error handling, rate limiting,
and security — reimplementing these is unnecessary and error-prone.
### Bulk Product Import
For large catalogs, use `bulk-upsert-products` instead of looping `create-product`:
```
execute_integration(
service: "product-catalog",
endpoint: "bulk-upsert-products",
input: {
"items": [
{"sku": "TSH-001", "name": "Classic Tee", "price_cents": 2999, "status": "active"},
{"sku": "TSH-002", "name": "V-Neck Tee", "price_cents": 3499, "status": "active"},
{"sku": "TSH-001", "price_cents": 2799}
]
}
)
```
Each item is matched by SKU: existing → update, new → create (needs `name` + `price_cents`).
Max 500 items per call. Response includes per-item status and `summary.by_error_type`.
**Always check `result.failed` and `result.summary.by_error_type`** — `success: true`
means the call itself worked, not that every item succeeded.
### Debugging with Request Tracer
When something isn't working — a page returns wrong data, an integration fails,
or performance is slow — use the Request Tracer to see exactly what happened:
1. **Start a trace session:**
```
execute_integration(
service: "tracer",
endpoint: "start",
input: { "ttl": 120, "include_optimizer": true }
)
→ returns hash (e.g., "tr_abc12345")
```
2. **Perform the operation that's failing** — create a page, submit a form, call an integration
3. **Read the trace:**
```
execute_integration(
service: "tracer",
endpoint: "logs",
input: { "hash": "tr_abc12345" }
)
```
The trace shows every API request and page render with HTTP method, path, status
code, duration, SQL query summary, and which server handled the request.
Integration failures include typed error data (`error_type`, `error_code`, and
`error_field` / `recovery` when applicable) so you can see exactly what went
wrong without guessing.
**When to use the tracer:**
- Page renders wrong content → trace optimizer request, check SQL queries
- Integration call fails → trace API request, check `error_type` and `recovery`
- Request is slow → check `duration_ms` and `db.total_ms` breakdown
- "It works sometimes" → `server` field shows which node handled each request
**Options:**
- `include_optimizer: true` — also trace public page renders (default: off)
- `include_sql: false` — skip SQL summary (default: on)
- `ttl: 10-300` — session duration in seconds (default: 60)
---
## PDF from Your Own Template — `pdf_document/render-template`
Two ways to make a PDF. `pdf_document/generate` takes content blocks and applies the
project's branding — fast, zero layout work. `render-template` renders a **project-defined
HTML template** with full data-binding — use it when the layout must be exact: invoices on
pre-printed stationery, packing slips, quotes, certificates. The template controls 100% of
the output; no platform branding is applied.
### The template is a PAPI asset
Upload the template like any asset (`upload_asset`, e.g. `templates/invoice.html`), iterate
with `patch_asset`. Rules:
- A **complete HTML document** with its own CSS. Set page margins in the template via
`@page { margin: ...; }` (A4 portrait). `letterhead_top_mm` exists as a convenience
override for pre-printed stationery, but defining `@page` yourself is preferred.
- **Layout + template tokens only. NEVER put customer data, order data, or secrets in a
template** — assets are public on the CDN. Data arrives at render time via `data`.
- DOMPDF renders it: use tables and inline styles for structure; `position:absolute` works
for fixed placement (address blocks). Font is **DejaVu Sans** — full glyph set incl. `€`.
- Caps: template ≤ 512 KB, rendered HTML ≤ 2 MB. Rate limit 60/hour.
### Template dialect — same engine as SSR pages
`{{var}}` (HTML-escaped — customer strings can never inject markup), `{{{var}}}` (raw,
only for values the template author controls), dot paths, `{{#if}}/{{#else}}/{{#unless}}`
with operators (`==`, `!=`, `>`, `<`, `>=`, `<=`, `contains`, `starts_with`, `ends_with`)
and full same-type nesting, `{{#each}}` **including nesting** (`{{this}}` for scalar items,
`@index`, `{{../parent}}`), filter chains.
Money is always **integer cents** on this platform. Format in the template, never in a
chain:
| Filter | In → out | Example |
|---|---|---|
| `money_eur` | cents → `€ 1.234,56` (NL) | `{{total_cents \| money_eur}}` |
| `vat_incl:21` | VAT-inclusive cents → VAT cents (fiscal rounding) | `{{total_cents \| vat_incl:21 \| money_eur}}` |
| `divide:N` | numeric division | `{{qty \| divide:2}}` |
| `date` | date → `13-08-2026` (**default d-m-Y**, format arg optional) | `{{paid_at \| date}}` |
| `number:2` / `currency:EUR` | NL notation | building blocks under `money_eur` |
Invoice-shaped template fragment (lines with sub-lines, conditional discount):
```html
{{#each lines}}
<tr><td>{{name}}</td><td class="right">{{qty}}</td><td class="right">{{price_cents | money_eur}}</td></tr>
{{#each subs}}<tr><td class="sub" colspan="3">{{this}}</td></tr>{{/each}}
{{/each}}
{{#if discount}}<p>Discount: {{discount | money_eur}}</p>{{/if}}
<p>Total: {{total_cents | money_eur}} — VAT (21%): {{total_cents | vat_incl:21 | money_eur}}</p>
```
### Calling it
`data` is the **root context** — its keys become the template's top-level variables.
```
execute_integration(service: "pdf_document", endpoint: "render-template", input: {
"template_slug": "templates/invoice.html",
"data": { "total_cents": 16170, "paid_at": "2026-08-13", "lines": [ ... ] },
"store": false, // false → in-memory, base64-only (email attachments)
"return_base64": true // default store=true → archived to the private documents
}) // bucket + signed download URL (never on the public CDN)
```
`data` must be a real object — a JSON *string* is rejected with a 422.
### External images/CSS — strict by design, self-reporting
- **Relative URLs are auto-rewritten to the project's own CDN**: `src="images/logo.png"`
just works.
- Allowed absolutes: `data:` URIs and `https://cdn.websitepublisher.ai/...`. Everything
else (other hosts, `http:`, protocol-relative) is **stripped** before rendering and
reported back as `data.blocked_assets` in the response. **Check that field after a test
render** — if your logo URL shows up there, upload it as a project asset and reference
it relatively.
### Automatic invoice printing — the `order_events` chain pattern
Thread the full order object as **one raw token** (exact single tokens keep their type),
then feed the PDF base64 into the mail step:
This is the `create-subscription` **input** — `steps` is a TOP-LEVEL field. Do NOT wrap
it in `config`: that is the *stored* shape you see back in `list-subscriptions`, and an
input `config` field is rejected.
```
execute_integration(service: "order_events", endpoint: "create-subscription", input: {
"event": "order.paid",
"target_type": "iapi_chain",
"steps": [
{ "service": "order-management", "endpoint": "get-order",
"input_template": { "order_id": "{{fields.order_id}}" } },
{ "service": "pdf_document", "endpoint": "render-template",
"input_template": {
"template_slug": "templates/invoice.html",
"data": { "order": "{{steps.0.result.order}}" },
"store": false, "return_base64": true } },
{ "service": "resend", "endpoint": "send-email",
"input_template": {
"from": "shop@yourdomain.com", "to": "printer@yourdomain.com",
"subject": "Invoice {{fields.order_id}}",
"text": "Attached.",
"attachments": [ { "filename": "invoice.pdf",
"content_base64": "{{steps.1.result.data.base64}}" } ] } }
]
})
```
Watch the resend attachment field: it is **`content_base64`** (not `content`). Need
per-line structured data (sizes, prescriptions, options)? Add an
`order-management/get-line-meta` step and pass its result alongside the order
(`"lens": "{{steps.1.result}}"`); omit `def_key` unless you have verified the stored
definition key, and copy the real meta key names from one live `get-line-meta` call.
The template then reads `{{order.total_cents | money_eur}}`, `{{#each order.lines}}`, etc.
Note: iapi_chain retries default to **off** (steps have real side effects).
### Testing & replaying the chain — `order_events/fire-event`
Never test a chain with a real payment. `fire-event` pushes ONE existing order through
the exact same payload/queue/retry path as a real transition:
```
execute_integration(service: "order_events", endpoint: "fire-event", input: {
"order_id": 42, "event": "order.paid", "dry_run": true
})
```
- **Always `dry_run:true` first** — it reports `would_fire` / `would_skip` per
subscription without enqueueing anything. Real fires are REAL: chains send real
mail and print real documents.
- An order+event already delivered to a subscription is skipped (dedup). **A FAILED
delivery blocks a new fire just the same** — the dedup row exists either way — so
re-running a failed delivery always needs `force: true`. `force` writes a distinct
replay key (`{order_id}:{event}:replay:{timestamp}`), keeping the original row and
the audit trail intact.
- Reprinting orders for a NEW subscription needs no `force` (no delivery rows exist
yet): create the subscription, verify one order, then fire per order.
- The response lists per subscription: `action` (`fired`/`skipped`/`would_fire`/
`would_skip`), `delivery_id`, and a `reason` on skips. Check the outcome afterwards
in `list-deliveries` (filter by `order_id` or `status`).
### Build workflow
1. Upload the template asset. 2. Test-render with `store:false` + sample `data`; decode
the base64 and check the PDF **and** `blocked_assets`. 3. Iterate via `patch_asset`.
4. Wire the chain. Errors are explicit: `TEMPLATE_NOT_FOUND`, `TEMPLATE_INVALID`
(non-`.html` / traversal), `TEMPLATE_TOO_LARGE`, `RENDER_OUTPUT_TOO_LARGE`.
---
## Admin-Protected Pages — IAPI Admin Auth
> **⚠️ Need to upload images from an admin panel?** Do NOT use `upload_asset`,
> vault keys, or MAPI asset routes from the browser. Use **Asset Proxy**
> (`/iapi/project/{id}/asset-proxy/upload` with your `wsa_` admin token) — it's
> the simplest option. See "Image Upload in Admin Panels" below.
When building dashboards, admin panels, or any page that requires a logged-in admin
(not a public visitor), use the IAPI Admin Auth pattern. This is separate from
SAPI Visitor Auth — they serve different purposes.
| Feature | Admin Auth (IAPI) | Visitor Auth (SAPI) |
|---|---|---|
| **Use case** | Admin dashboards, CMS, internal tools | Member areas, gated content, loyalty portals |
| **Login method** | Email + password | Magic link or verification code |
| **Token storage** | `sessionStorage.admin_token` | Managed by sapi-client.js internally |
| **API calls** | Direct `fetch()` to `/iapi/project/{id}/...` with `Authorization: Bearer` | `WP.sapi(id).call(...)` via CDN library |
| **Token prefix** | `wsa_` (server-side) | Session ID (no token exposed to page) |
### Admin Login
```javascript
const PROJECT_ID = 12345; // replace with actual project ID
async function login(email, password) {
const r = await fetch(`/iapi/project/${PROJECT_ID}/admin-auth/login`, {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({email, password})
});
const data = await r.json();
if (data.success && data.token) {
sessionStorage.setItem('admin_token', data.token);
localStorage.setItem('admin_token', data.token);
document.cookie = `admin_token=${data.token}; path=/; max-age=28800; SameSite=Lax`;
}
return data;
}
```
Triple storage (sessionStorage + localStorage + cookie) ensures the token survives
page navigations, tab reopens, and server-side middleware checks.
After login, redirect to **`/`** if your dashboard page is set as `landingpage: true`.
See the note about `landingpage` under Page Metadata.
### Admin-Only IAPI Calls
```javascript
async function callAdmin(service, endpoint, payload) {
const token = sessionStorage.getItem('admin_token');
if (!token) { window.location.replace('/login'); return; }
const r = await fetch(`/iapi/project/${PROJECT_ID}/${service}/${endpoint}`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer ' + token
},
body: JSON.stringify(payload)
});
if (r.status === 401) {
sessionStorage.removeItem('admin_token');
localStorage.removeItem('admin_token');
window.location.replace('/login');
return;
}
return r.json();
}
// Usage:
const leads = await callAdmin('leads', 'get-leads', { page: 1, per_page: 25 });
const msg = await callAdmin('anthropic', 'create-message', { prompt: '...' });
```
**Important:** Use direct `fetch()` — not `WP.sapi().call()`. The SAPI client library
is for visitor sessions. Admin calls use `Authorization: Bearer` headers on `/iapi/` routes.
### Page Rendering — Auth Guard
```html
<body>
<script>
// Immediate redirect — no hidden body, no async check
var token = sessionStorage.getItem('admin_token')
|| localStorage.getItem('admin_token');
if (!token) window.location.replace('/login');
</script>
<!-- page content renders immediately for authenticated users -->
<h1>Dashboard</h1>
<!-- ... -->
<!-- WPE-DEBUG path=api slug=skills/websitepublisher-api/SKILL.md -->
<script src="https://cdn.websitepublisher.ai/wpe/loader.js" data-project="22254" data-page="skills/websitepublisher-api/SKILL.md" defer></script>
<style>
.wps-lang-banner{position:fixed;top:0;left:0;right:0;z-index:99999;transform:translateY(-100%);transition:transform .35s cubic-bezier(.4,0,.2,1);font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif}
.wps-lang-banner.wps-lb-visible{transform:translateY(0)}
.wps-lang-banner-inner{display:flex;align-items:center;justify-content:center;gap:10px;padding:10px 48px 10px 20px;background:linear-gradient(135deg,#6C5CE7 0%,#7C6CF7 100%);color:#fff;font-size:14px;line-height:1.4;text-align:center;position:relative}
.wps-lang-banner a{color:#fff;font-weight:600;text-decoration:underline;text-underline-offset:2px;white-space:nowrap}
.wps-lang-banner a:hover{opacity:.85}
.wps-lang-banner-close{position:absolute;right:14px;top:50%;transform:translateY(-50%);background:none;border:none;color:rgba(255,255,255,.8);font-size:18px;cursor:pointer;padding:4px 8px;line-height:1}
.wps-lang-banner-close:hover{color:#fff}
.wps-lang-banner-flag{font-size:18px}
@media(max-width:600px){.wps-lang-banner-inner{font-size:13px;padding:9px 40px 9px 14px;gap:8px;flex-wrap:wrap}.wps-lang-banner-close{right:8px}}
</style><script>(function(){var LC={"nl":{"flag":"🇳🇱","text":"Deze pagina is ook beschikbaar in het Nederlands","cta":"Bekijk in het Nederlands"},"de":{"flag":"🇩🇪","text":"Diese Seite ist auch auf Deutsch verfügbar","cta":"Auf Deutsch ansehen"},"fr":{"flag":"🇫🇷","text":"Cette page est aussi disponible en français","cta":"Voir en français"},"es":{"flag":"🇪🇸","text":"Esta página también está disponible en español","cta":"Ver en español"}};var CN="wps_lang_pref";
function gC(n){var m=document.cookie.match(new RegExp("(?:^|; )"+n+"=([^;]*)"));return m?decodeURIComponent(m[1]):null}
function sC(n,v){document.cookie=n+"="+v+";path=/;max-age=31536000;SameSite=Lax"}
if(gC(CN))return;
var p=window.location.pathname;
if(/^\/[a-z]{2}(\/|$)/.test(p))return;
var bl=(navigator.language||navigator.userLanguage||"").toLowerCase().split("-")[0];
if(!LC[bl])return;
var c=LC[bl];
var nl="/"+bl+p;
var d=document.createElement("div");
d.className="wps-lang-banner";
d.innerHTML='<div class="wps-lang-banner-inner"><span class="wps-lang-banner-flag">'+c.flag+"</span><span>"+c.text+' — <a href="'+nl+'">'+c.cta+" →</a></span>"+'<button class="wps-lang-banner-close" aria-label="Dismiss">×</button></div>';
document.body.appendChild(d);
setTimeout(function(){d.classList.add("wps-lb-visible")},100);
d.querySelector("a").addEventListener("click",function(){sC(CN,bl)});
d.querySelector(".wps-lang-banner-close").addEventListener("click",function(){d.classList.remove("wps-lb-visible");setTimeout(function(){d.remove()},400);sC(CN,"en")});})();</script>
</body>
```
**Never do this:**
```html
<!-- ❌ FORBIDDEN — causes flash of invisible content, breaks on slow connections -->
<body style="visibility:hidden">
<script>
checkAuth().then(() => document.body.style.visibility = 'visible');
</script>
```
The correct pattern is: redirect immediately if no token, render normally if token exists.
Auth validation happens on the first API call — if the token is expired, the 401 handler
clears storage and redirects to login.
### Logout
```javascript
function logout() {
sessionStorage.removeItem('admin_token');
localStorage.removeItem('admin_token');
document.cookie = 'admin_token=; path=/; max-age=0';
window.location.replace('/login');
}
```
### Creating Admin Users — the bootstrap order
There is no dashboard screen for creating Admin Auth users. The first admin is created
through the API, and the customer's own password never has to pass through you, through
the platform owner, or through any chat session.
The four steps only work in this order:
```
create_user (random throwaway password)
→ request-reset (requires NO login)
→ reset-password (the user sets their own password)
→ login
```
**Step 1 — create the account with a throwaway password.**
```
execute_integration(
project_id: 12345,
service: "admin_auth",
endpoint: "create_user",
input: { email: "admin@example.com", password: "<40 random characters>" }
)
```
Generate the password randomly, never show it to the user, and never store it. It exists
only so the account row exists. `create_user` accepts only `email` and `password` — no
name field. The email is the unique identifier and the login credential.
**Step 2 — the user requests a reset link.** `request-reset` needs no session and no
token. That is what makes the bootstrap self-service.
```
POST /iapi/project/{id}/admin-auth/request-reset
{ "email": "admin@example.com" }
```
**`request-reset` only works for an existing, active user.** An unknown address returns
`{"success": true}` and sends nothing — that is the enumeration guard, not a failure.
Reset alone therefore does not solve the bootstrap; `create_user` + reset together do.
**Step 3 — the user sets their own password.**
```
POST /iapi/project/{id}/admin-auth/reset-password
{ "token": "rst_...", "password": "...", "password_confirmation": "..." }
```
`password_confirmation` is required. Minimum 8 characters. The token is single-use and
expires 60 minutes after it was requested. A successful reset invalidates all active
sessions for that user.
**Step 4 — login**, as described in the canonical path table below.
#### You must build two pages — they do not exist by default
This is the step that gets missed, and it is the reason the flow appears to be missing
from the platform. Creating the user is not enough: without these two pages there is no
screen to start from.
| Page | Does | Link from |
|------|------|-----------|
| `forgot-password.html` | email field → `POST .../admin-auth/request-reset` | `login.html` |
| `reset-password.html` | reads `token` from the query string → `POST .../admin-auth/reset-password` | the emailed link |
Three rules for those pages:
1. **Both pages must be publicly reachable.** No visitor session, no OTP gate, no auth
check. The `rst_` token is the proof of identity. If you put the reset page behind the
site's own login, the user needs a password to set their password.
2. **Hard-code the project ID in `reset-password.html`.** The emailed URL is
`{base}/reset-password.html?token=rst_xxx&project={website_id}` — that parameter is the
*website* ID, while the IAPI route runs on the *dashproject* ID. Reading it from the
query string produces a page that posts to the wrong project and fails silently, at the
exact moment the user believes they are done. Ignore the parameter, use the project
number you built the site with.
3. **Keep the confirmation generic.** Say "if an account exists for this address, a link is
on its way" — never "unknown address". That preserves the enumeration guard.
Set `noindex,nofollow` on both.
#### Delivery
The reset mail goes out over the AuthMailer cascade: custom SMTP → the project's own
Resend key → the platform. A project with no mail provider configured still receives the
mail, sent from a platform address. Configuring Resend is not a prerequisite — do not tell
a customer it is.
#### There is no change-password endpoint
A signed-in admin cannot change their own password. The browser endpoints are `login`,
`verify`, `logout`, `refresh`, `request-reset` and `reset-password`. The reset flow is also
the route for a voluntary password change — it is the design, not a workaround.
`update_password` does exist, but it is an MCP tool: it is admin-side, it means someone
other than the user chooses the password, and it invalidates all that user's sessions. Use
it only as a last resort, never as the normal path.
### Decision Tree — Which Auth System?
```
Does the page need login?
├── No → No auth needed (public page)
└── Yes
├── Is the user an admin/owner managing content?
│ └── Use Admin Auth (IAPI) — see "Admin-Protected Pages"
└── Is the user a member/end-user?
├── Open enrolment — anyone with an email may enter (loyalty, gated freebies)?
│ └── Use Visitor Auth (SAPI) — see "Contact Forms (SAPI)"
└── Provisioned/closed membership — you control access, paid tiers, tenant isolation?
└── Use Tenant Auth (IAPI) — see "Tenant-Protected Pages"
```
### Common Pitfalls — Why Admin Auth Has Its Own Pattern
Multiple AI builds have walked into the same trap: trying to call admin endpoints
via the SAPI execute route (`WP.sapi().call('/execute/admin_auth/login', ...)`).
That path requires a visitor session bootstrap and CSRF tokens — machinery the SAPI
library wraps for visitor forms but that does not align with how admin auth issues
and validates `wsa_` Bearer tokens.
**The canonical admin auth path is always:**
| Step | Call | Auth header |
|------|------|------------|
| 1. Login | `POST /iapi/project/{id}/admin-auth/login` | None — body has email + password |
| 2. Store token | sessionStorage + localStorage + cookie | — |
| 3. Authenticated calls | `POST /iapi/project/{id}/{service}/{endpoint}` | `Authorization: Bearer wsa_...` |
| 4. Verify on page load | `POST /iapi/project/{id}/admin-auth/verify` | None — body has token |
| 5. Logout | `POST /iapi/project/{id}/admin-auth/logout` | None — body has token |
**Anti-patterns — never do these for admin auth:**
- ❌ `WP.sapi().call('/execute/admin_auth/login', ...)` — that route is for visitor SAPI flows
- ❌ Manual `GET /sapi/session` + `X-CSRF-Token` headers — admin auth doesn't use the SAPI session layer
- ❌ Reading the token from `r.data.token` after a SAPI execute call — wrong envelope shape
- ❌ `<body style="visibility:hidden">` while running an async auth check — see Page Rendering above
- ❌ URL with underscore for login/verify/logout: `/iapi/project/{id}/admin_auth/login` — those specific routes are `admin-auth` (hyphen)
- ❌ Pointing the user at the WebsitePublisher dashboard to create or set an admin password — **that screen does not exist**. Admin users are created via `create_user`; passwords are set by the user through `request-reset` → `reset-password`
- ❌ Building a login page without a link to `forgot-password.html` — the first admin then has no way to set a password, and the account is unreachable
The IAPI route is fully self-contained: no session, no CSRF, just `Authorization: Bearer`
on the request. If you find yourself adding session bootstrap or CSRF token logic to an
admin page, stop — you've taken the wrong turn.
### Image Upload in Admin Panels
Admin panels often need image upload — for portfolio management, product photos, team
pictures, or any content the admin manages visually.
There are two approaches. **Asset Proxy** stores files in the PAPI asset system (visible
in `list_assets`, manageable). **SAPI upload** stores files in the form uploads bucket.
Both return CDN URLs. Choose based on whether you need the files in the project's asset system.
#### Option A — Asset Proxy (recommended for admin panels)
Uses the admin's existing `wsa_` token. No extra setup needed — no SAPI form, no CDN script.
Files go into the PAPI asset system.
```javascript
const PROJECT_ID = 12345;
function getAdminToken() {
return sessionStorage.getItem('admin_token');
}
// Convert file to base64
function fileToBase64(file) {
return new Promise(function(resolve, reject) {
var reader = new FileReader();
reader.onload = function() { resolve(reader.result.split(',')[1]); };
reader.onerror = reject;
reader.readAsDataURL(file);
});
}
// Upload via asset-proxy (uses admin token, no WPA key needed)
async function uploadImage(file, slug) {
var base64 = await fileToBase64(file);
var res = await fetch('/iapi/project/' + PROJECT_ID + '/asset-proxy/upload', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer ' + getAdminToken()
},
body: JSON.stringify({
slug: slug, // e.g. "images/product-42.jpg"
base64: base64,
overwrite: true
})
});
if (res.status === 401) { window.location.replace('/login'); return; }
var data = await res.json();
if (data.success) {
return data.asset_url; // CDN URL: cdn.websitepublisher.ai/custom/wid.../images/...
}
throw new Error(data.message || 'Upload failed');
}
// Combined: upload image, then save product
document.getElementById('product-form').addEventListener('submit', async function(e) {
e.preventDefault();
var file = document.getElementById('photo').files[0];
var name = document.getElementById('name').value;
var slug = 'images/product-' + Date.now() + '.' + file.name.split('.').pop();
var imageUrl = file ? await uploadImage(file, slug) : null;
await saveProduct(name, imageUrl); // IAPI call with wsa_ token (see Admin-Only IAPI Calls)
});
```
#### Option B — SAPI Upload (alternative, requires form setup)
```javascript
const PROJECT_ID = 12345;
var sapi = WP.sapi(PROJECT_ID); // SAPI session for uploads
// Admin is logged in — wsa_ token in sessionStorage (see Admin Login above)
function getAdminToken() {
return sessionStorage.getItem('admin_token');
}
// Image upload — uses SAPI (no admin token needed)
async function uploadImage(file) {
var res = await sapi.uploadFile('admin_upload', file);
if (res.ok) {
return res.data.data.asset_url; // CDN URL: cdn.websitepublisher.ai/custom/wid.../images/...
}
throw new Error(res.data.error?.message || 'Upload failed');
}
// Save data with image URL — uses admin auth (wsa_ token)
async function saveProduct(name, imageUrl) {
var res = await fetch('/iapi/project/' + PROJECT_ID + '/product-catalog/create-product', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer ' + getAdminToken()
},
body: JSON.stringify({ name: name, image_url: imageUrl })
});
if (res.status === 401) { window.location.replace('/login'); return; }
return res.json();
}
// Combined flow: upload image, then save record
document.getElementById('product-form').addEventListener('submit', async function(e) {
e.preventDefault();
var file = document.getElementById('photo').files[0];
var name = document.getElementById('name').value;
var imageUrl = file ? await uploadImage(file) : null;
await saveProduct(name, imageUrl);
});
```
#### Setup Requirements
For image upload to work in an admin panel, you need:
1. **A SAPI form configured** for the upload (even a minimal one):
```
configure_form(
project_id: 12345,
form_name: "admin_upload",
required_fields: [],
action: { type: "none" },
max_submits_per_session: 20
)
```
2. **The CDN script** on the page:
```html
<script src="https://cdn.websitepublisher.ai/js/sapi-client.js"></script>
```
3. **Admin auth** already working (see Admin Login above)
#### How the Auth Systems Coexist
| Operation | Auth system | Token | Endpoint |
|---|---|---|---|
| Admin login | IAPI Admin Auth | `wsa_` | `/iapi/project/{id}/admin-auth/login` |
| Read/write data | IAPI | `wsa_` Bearer | `/iapi/project/{id}/{service}/{endpoint}` |
| Upload image (Option A) | IAPI Asset Proxy | `wsa_` Bearer | `/iapi/project/{id}/asset-proxy/upload` |
| Upload image (Option B) | SAPI | Session + CSRF | `/sapi/project/{id}/form/upload` |
| Result | — | — | CDN URL in `asset_url` response field |
With **Option A** (asset-proxy), everything uses the same `wsa_` admin token — simpler code,
no second auth system needed.
With **Option B** (SAPI upload), the SAPI session lives separately in
`sessionStorage.wp_{projectId}_sid` and never conflicts with the admin token.
#### Common Mistake
Do NOT try to upload images via `upload_asset` or MAPI asset routes from the browser.
Those are MCP/API tools, not browser endpoints.
**These approaches will NOT work for browser-based uploads:**
- `POST /mapi/project/{id}/assets` with `wsa_` token → 401 (wsa_ not accepted for asset writes)
- `/iapi/project/{id}/upload-asset` → 404 (does not exist)
- A made-up top-level route like `/project/{id}/upload-asset` (missing the `{service}` segment) → 404 — asset writes are `asset_proxy/upload`; the IAPI route shape is always `/project/{id}/{service}/{endpoint}`
- Vault keys (`{{vault:wpa_...}}`) in browser JavaScript → vault refs are server-side only
- Custom API proxy with vault key → proxy passes the literal string, not the resolved value
**Use Asset Proxy (Option A) or SAPI upload (Option B)** — both handle auth correctly
and return CDN URLs. Asset Proxy is simpler because it uses the same `wsa_` token
you already have for data operations.
**Asset Proxy is not images-only.** It accepts any `slug` and stores any bytes in the
PAPI asset system. To write or refresh a JSON/CSV/text data file from an admin panel
(e.g. regenerating a products snapshot at `data/products-snapshot.json`), base64-encode
the text and POST the same `{ slug, base64, overwrite: true }` body — no special
"snapshot" or "data" route exists or is needed. Server-side (agent/MCP), use
`upload_asset(content_text=…, overwrite=true)` instead.
### Vault-Based API Keys (AI-Requested)
When building admin panels or integrations that need server-side API access,
the AI can request a project key **without ever seeing the raw token**.
The project owner approves via email — the key goes directly into the vault.
#### The Flow
1. **AI requests a key:**
```
execute_integration(
project_id: 12345,
service: "auth_keys",
endpoint: "request-key",
input: {
vault_key_name: "wpa_dashboard",
purpose: "Leads dashboard — read and update leads"
}
)
```
Response: `{ status: "pending_approval", request_id: "req_a1b2c3..." }`
2. **Project owner receives email** → clicks confirmation link → key is created
3. **AI checks status** (optional, same session):
```
execute_integration(
project_id: 12345,
service: "auth_keys",
endpoint: "check-status",
input: { request_id: "req_a1b2c3..." }
)
```
Response: `{ status: "approved" }` (or `"pending"` / `"expired"`)
4. **AI uses the vault reference** in IAPI proxy calls, scheduled tasks, or page templates:
`{{vault:...}}` with the key name from step 1 (here: `wpa_dashboard`)
The AI never sees the actual token. The key exists only in the vault and is resolved
server-side by the IAPI proxy.
#### Key Rules
- `vault_key_name` **must** start with `wpa_` (prevents overwriting other vault secrets)
- `purpose` is required — it's shown to the owner in the confirmation email
- Max 2 pending requests per project at a time
- Unconfirmed requests expire after 1 hour
- Each confirmation link works only once
#### When to Use This
Use `auth_keys` when a page or scheduled task needs to make authenticated API calls
and no WPA key exists in the vault yet. Common scenarios: admin dashboards,
automated data sync tasks, headless API integrations.
Do NOT use this for visitor-facing pages — those use SAPI sessions (no Bearer token needed).
---
## Tenant-Protected Pages — Member Portal (tenant_auth)
When building a **provisioned membership community** — paid tiers, courses, a private
content library, any portal where *you* control who has access — use **Tenant Auth**.
This is a third auth system, distinct from Admin Auth and Visitor Auth:
| | Admin Auth (IAPI) | **Tenant Auth (IAPI)** | Visitor Auth (SAPI) |
|---|---|---|---|
| **Use case** | Single site-admin/owner managing content | **Provisioned members, paid tiers, tenant-isolated portals** | Open member areas — anyone with an email may self-enrol |
| **Who can log in** | The admins you create | **Only members you provision** (`require_provisioned`, default on) | Anyone who receives a magic link/code |
| **Login method** | Email + password | **Email OTP and/or password** (per-project config) | Magic link or code |
| **Isolation** | — | **`tenant_code` per member** | — |
| **Tokens** | `wsa_` | **`wst_` access + `rft_` rotating refresh** | Session ID (no token on page) |
| **Route** | `/iapi/project/{id}/admin-auth/...` | **`/iapi/project/{id}/tenant-auth/...`** | `WP.sapi(id).call(...)` |
The `tenant-auth` route is **public and self-contained**: the project id is in the URL,
so there is **no API key, no SAPI session, and no CSRF** — plain `fetch()` from the page.
Use a **relative path** (`/iapi/project/{id}/tenant-auth/...`). Since August 2026 every
published site — wildcard subdomain and custom domain alike — proxies `/sapi/`, `/iapi/`,
`/mapi/` and `/wpe/` straight to the API, so a relative call is same-origin: no CORS
preflight, and any session cookie stays first-party. The absolute host
`https://api.websitepublisher.ai` still works and remains valid for existing pages.
### Provisioning members (you control the list)
Members are created server-side via MCP — never from the browser:
```
execute_integration(
project_id: 12345,
service: "tenant_auth",
endpoint: "create_user",
input: { email: "member@example.com", tenant_code: "community", password: "optional", role: "member" }
)
```
Omit `password` for a **code-only (passwordless) member**. With `require_provisioned`
on (default), only emails you have created can authenticate — that is what makes the
membership *closed*. Related MCP endpoints: `list_users`, `delete_user` (deactivates +
kills all sessions), `update_password`, `set_tenant_code`, `list_sessions`, and
`configure` (set `methods` = `email_otp` / `password`, `success_url`, and token TTLs).
### Member Login
**Method A — email OTP (passwordless, default):**
```javascript
const PROJECT_ID = 12345; // replace with actual project ID
// 1. request a 6-digit code by email (always returns success — no user enumeration)
await fetch(`/iapi/project/${PROJECT_ID}/tenant-auth/request-code`, {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({ email })
});
// 2. verify the code → access + refresh token
const r = await fetch(`/iapi/project/${PROJECT_ID}/tenant-auth/verify-code`, {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({ email, code })
});
const data = await r.json();
// { success, tenant_code, success_url, token: 'wst_...', refresh_token: 'rft_...' }
```
**Method B — email + password** (only when the `password` method is enabled):
```javascript
const r = await fetch(`/iapi/project/${PROJECT_ID}/tenant-auth/login`, {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({ email, password })
});
const data = await r.json(); // same shape as verify-code
```
On success, store **both** tokens (triple storage survives navigation, tab reopen, and
middleware checks) and redirect to `data.success_url` (or `/`):
```javascript
if (data.success && data.token) {
sessionStorage.setItem('tenant_token', data.token);
localStorage.setItem('tenant_token', data.token);
localStorage.setItem('tenant_refresh', data.refresh_token);
document.cookie = `tenant_token=${data.token}; path=/; max-age=86400; SameSite=Lax`;
window.location.replace(data.success_url || '/');
}
```
### Page Rendering — Auth Guard
Immediate redirect if there is no token — **never** a hidden body with an async check:
```html
<body>
<script>
var token = sessionStorage.getItem('tenant_token')
|| localStorage.getItem('tenant_token');
if (!token) window.location.replace('/login');
</script>
<!-- content renders immediately for members -->
<h1>Members Area</h1>
<!-- WPE-DEBUG path=api slug=skills/websitepublisher-api/SKILL.md -->
<script src="https://cdn.websitepublisher.ai/wpe/loader.js" data-project="22254" data-page="skills/websitepublisher-api/SKILL.md" defer></script>
<style>
.wps-lang-banner{position:fixed;top:0;left:0;right:0;z-index:99999;transform:translateY(-100%);transition:transform .35s cubic-bezier(.4,0,.2,1);font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif}
.wps-lang-banner.wps-lb-visible{transform:translateY(0)}
.wps-lang-banner-inner{display:flex;align-items:center;justify-content:center;gap:10px;padding:10px 48px 10px 20px;background:linear-gradient(135deg,#6C5CE7 0%,#7C6CF7 100%);color:#fff;font-size:14px;line-height:1.4;text-align:center;position:relative}
.wps-lang-banner a{color:#fff;font-weight:600;text-decoration:underline;text-underline-offset:2px;white-space:nowrap}
.wps-lang-banner a:hover{opacity:.85}
.wps-lang-banner-close{position:absolute;right:14px;top:50%;transform:translateY(-50%);background:none;border:none;color:rgba(255,255,255,.8);font-size:18px;cursor:pointer;padding:4px 8px;line-height:1}
.wps-lang-banner-close:hover{color:#fff}
.wps-lang-banner-flag{font-size:18px}
@media(max-width:600px){.wps-lang-banner-inner{font-size:13px;padding:9px 40px 9px 14px;gap:8px;flex-wrap:wrap}.wps-lang-banner-close{right:8px}}
</style><script>(function(){var LC={"nl":{"flag":"🇳🇱","text":"Deze pagina is ook beschikbaar in het Nederlands","cta":"Bekijk in het Nederlands"},"de":{"flag":"🇩🇪","text":"Diese Seite ist auch auf Deutsch verfügbar","cta":"Auf Deutsch ansehen"},"fr":{"flag":"🇫🇷","text":"Cette page est aussi disponible en français","cta":"Voir en français"},"es":{"flag":"🇪🇸","text":"Esta página también está disponible en español","cta":"Ver en español"}};var CN="wps_lang_pref";
function gC(n){var m=document.cookie.match(new RegExp("(?:^|; )"+n+"=([^;]*)"));return m?decodeURIComponent(m[1]):null}
function sC(n,v){document.cookie=n+"="+v+";path=/;max-age=31536000;SameSite=Lax"}
if(gC(CN))return;
var p=window.location.pathname;
if(/^\/[a-z]{2}(\/|$)/.test(p))return;
var bl=(navigator.language||navigator.userLanguage||"").toLowerCase().split("-")[0];
if(!LC[bl])return;
var c=LC[bl];
var nl="/"+bl+p;
var d=document.createElement("div");
d.className="wps-lang-banner";
d.innerHTML='<div class="wps-lang-banner-inner"><span class="wps-lang-banner-flag">'+c.flag+"</span><span>"+c.text+' — <a href="'+nl+'">'+c.cta+" →</a></span>"+'<button class="wps-lang-banner-close" aria-label="Dismiss">×</button></div>';
document.body.appendChild(d);
setTimeout(function(){d.classList.add("wps-lb-visible")},100);
d.querySelector("a").addEventListener("click",function(){sC(CN,bl)});
d.querySelector(".wps-lang-banner-close").addEventListener("click",function(){d.classList.remove("wps-lb-visible");setTimeout(function(){d.remove()},400);sC(CN,"en")});})();</script>
</body>
```
Then confirm the token server-side on load to get the member's identity, and to catch
expired/revoked sessions:
```javascript
const v = await fetch(`/iapi/project/${PROJECT_ID}/tenant-auth/verify`, {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({ token: localStorage.getItem('tenant_token') })
});
const info = await v.json(); // { valid, email, tenant_code, tenant_user_id }
if (!info.valid) {
// try refresh (below); if that fails, clear storage + redirect to /login
}
```
### Refreshing the session
Access tokens are short-lived (default 24h); refresh tokens last longer (default 14d)
and **rotate on every use** — the old pair is invalidated immediately:
```javascript
const r = await fetch(`/iapi/project/${PROJECT_ID}/tenant-auth/refresh`, {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({ refresh_token: localStorage.getItem('tenant_refresh') })
});
const data = await r.json(); // new { token, refresh_token }
// store the NEW token + refresh_token — the previous ones no longer work
```
Refresh when `verify` reports `valid:false`, or when an authenticated call returns 401.
### Logout
```javascript
await fetch(`/iapi/project/${PROJECT_ID}/tenant-auth/logout`, {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({ token: localStorage.getItem('tenant_token') })
});
sessionStorage.removeItem('tenant_token');
localStorage.removeItem('tenant_token');
localStorage.removeItem('tenant_refresh');
document.cookie = 'tenant_token=; path=/; max-age=0';
window.location.replace('/login');
```
### Canonical path — always
| Step | Call | Auth header |
|------|------|------------|
| 1a. Request code (OTP) | `POST /iapi/project/{id}/tenant-auth/request-code` | None — body `{email}` |
| 1b. Or password login | `POST /iapi/project/{id}/tenant-auth/login` | None — body `{email,password}` |
| 2. Verify code → tokens | `POST /iapi/project/{id}/tenant-auth/verify-code` | None — body `{email,code}` |
| 3. Store token + refresh_token | session + local + cookie | — |
| 4. Verify on page load | `POST /iapi/project/{id}/tenant-auth/verify` | None — body `{token}` |
| 5. Refresh (on 401 / expiry) | `POST /iapi/project/{id}/tenant-auth/refresh` | None — body `{refresh_token}` |
| 6. Logout | `POST /iapi/project/{id}/tenant-auth/logout` | None — body `{token}` |
### Calling SAPI as a signed-in member
Once the member has a `wst_` token, every SAPI call goes through the CDN client. Hand it
the token once per page load:
```html
<script src="https://cdn.websitepublisher.ai/js/sapi-client.js"></script>
<script>
var sapi = WP.sapi(PROJECT_ID);
var token = sessionStorage.getItem('tenant_token') || localStorage.getItem('tenant_token');
if (token) { sapi.setBearer(token); } // or: WP.sapi(PROJECT_ID, { bearer: token })
</script>
```
The server reads that token from the `Authorization` header and **nowhere else** — not a
cookie, not the body, not a query parameter — so without `setBearer()` the call arrives
without an identity and is refused with 401. That is correct behaviour, not a bug.
| Need | Call |
|---|---|
| JSON to an execute endpoint | `sapi.call('POST', '/execute/{service}/{endpoint}', {…})` |
| Bytes (multipart) to an execute endpoint | `sapi.callUpload('/execute/{service}/{endpoint}', { file: f, … }, onProgress)` |
| Member logs out | `sapi.clearBearer()` alongside clearing your own stored token |
**Do not hand-write `fetch()` for these.** The client carries the session, the CSRF token
and — the part that matters — recovery from a session that expired server-side: on a 401
it clears the cached session, fetches a fresh one and retries once. A hand-written call
gets none of that, and the failure is silent and permanent for the visitor.
Two things to know about the response:
- A refusal arrives as **HTTP 200 with `success: false`**. `res.ok` alone proves nothing;
always check `res.data.success === true`. The real code is in `res.data.upstream_status`.
- `callUpload()` cannot tell an oversized body from a stale CSRF token: once PHP's
`post_max_size` is passed it discards `$_POST` entirely and the CSRF check fails on empty
input. Keep a `file.size` check in the page — the page knows its own limit, the library
does not.
> Use these paths as-is from the browser — they resolve against the site's own origin on
> every published domain. Prefixing them with `https://api.websitepublisher.ai` also works.
Once a member is signed in, do **not** query MAPI from the browser to show them their own
data. Use the `account` integration — see **Member Self-Profile**.
### Anti-patterns — never do these for tenant auth
- ❌ SAPI execute: `POST /sapi/project/{id}/execute/tenant_auth/verify` — the post-login
actions return **403 "not accessible via visitor session"**. They are served by the
dedicated `tenant-auth` IAPI route, not SAPI. (request-code/verify-code/login are the
only tenant_auth actions reachable via SAPI; use the IAPI route for everything.)
- ❌ URL with underscore: `/iapi/project/{id}/tenant_auth/login` — those routes are
`tenant-auth` (**hyphen**). The underscore path hits the generic execute route
(Bearer-key + CSRF) and returns **419/401**.
- ❌ A relative path to a prefix that is **not** proxied: `/papi/`, `/wapi/`, `/vapi/`,
`/dapi/`, `/capi/`. Only `/sapi/`, `/iapi/`, `/mapi/` and `/wpe/` are reachable from a
published domain. The site serves everything else, so you get the HTML 404 page and
parsing it as JSON throws `Unexpected token '<'`. Use `https://api.websitepublisher.ai`
for those — and never from browser JS if they need a key.
- ❌ Putting a `wsa_`/`wpa_` API key in browser JS to reach tenant auth — not needed and
a security violation. The `tenant-auth` route needs no key.
- ❌ `<body style="visibility:hidden">` with an async auth check — use immediate redirect
(see Page Rendering).
The route is fully self-contained: no session, no CSRF, no API key. `verify`/`refresh`/
`logout` act on the token in the body, so a member can only affect **their own** session.
### Which auth system?
- **Tenant Auth (this section)** — provisioned/closed membership; you control the member
list; paid tiers, courses, private libraries; `tenant_code` isolation; password and/or OTP.
- **Visitor Auth (SAPI)** — open member areas where anyone with an email may self-enrol
(loyalty, gated freebies, newsletters). See "Contact Forms (SAPI)".
- **Admin Auth (IAPI)** — a single site-admin/owner managing content. See "Admin-Protected Pages".
## Member File Downloads — Gated Files
For files only paying or provisioned members may download — ebooks, course material,
paid reports — use the **gated-files** integration.
Files live on a **non-public bucket** — there is never a permanent public URL.
Every download is checked **live** against the member's session and entitlement, so a
refund/cancel (`delete_user`) revokes access instantly.
**When to use which:**
| | gated-files | file-downloads |
|---|---|---|
| **File location** | Private bucket (never publicly reachable) | Public CDN (URL works forever once seen) |
| **Access check** | Live tenant session + entitlement, per download | Static token embedded in the page |
| **Revocation** | Instant — session/grant revoked → next call 403 | Revoke the token; the CDN URL itself stays public |
| **Use for** | Paid/member content: ebooks, courses, reports | Free lead magnets, low-risk downloads |
### Setup (MCP)
```
# 1. Project defaults — entitlement + delivery
execute_integration(project_id: 12345, service: "gated-files", endpoint: "configure",
input: { entitlement_mode: "library", delivery_mode: "signed", signed_ttl_secs: 120 })
# 2. Register a file (exactly ONE source: storage_key | base64 | source_url)
execute_integration(project_id: 12345, service: "gated-files", endpoint: "put-file",
input: { filename: "ebook.pdf", content_type: "application/pdf",
source_url: "https://cdn.websitepublisher.ai/project12345/files/ebook.pdf" })
# → returns { id, storage_key } — the file now lives on the PRIVATE bucket
```
- `entitlement_mode`: `library` — any active member of the file's `tenant_code` (all
tenants of the site when omitted) | `asset` — explicit per-file grants via
`grant`/`revoke` (`grant_type`: `tenant_code` or `tenant_user`).
- `delivery_mode`: `signed` (short-lived presigned URL, storage serves the bytes —
default) | `stream` (the platform streams the bytes). The **browser code is identical**
for both.
- `source_url` accepts **our own public storage only** (SSRF guard). To ingest a file
that lives elsewhere: upload it as a normal project asset first, then pass that CDN
URL — and delete the public copy afterwards.
- Other MCP endpoints: `grant`, `revoke`, `list-files`, `stats`.
### Browser flow — member downloads a file
Requires a logged-in tenant member (`wst_` token — see "Tenant-Protected Pages") plus a
SAPI session for CSRF:
```javascript
const sapi = WP.sapi(PROJECT_ID);
sapi.setBearer(localStorage.getItem('tenant_token')); // once per page load
// Ask for a download URL. Session, CSRF and stale-session recovery are the
// client's job — see "Calling SAPI as a signed-in member".
const res = await sapi.call('POST', '/execute/gated-files/download', { file_id: 42 });
if (!res.data.success) {
console.warn(res.data.error, res.data.upstream_status); // see Shared Member Content
return;
}
const data = res.data.result; // { url, expires_in, delivery, filename }
// Fetch the file within expires_in (seconds) — the URL is short-lived
if (data.url) window.location.href = data.url;
```
A `401 "Tenant authentication required"` means the member's `wst_` is missing or expired:
refresh or re-login. An expired **SAPI session** needs no handling here — the client
clears it and retries once on its own.
### Browser flow — member adds a file
`put-upload` takes bytes from a member and writes them straight to the private bucket, so
nothing is ever momentarily public. `tenant_code` comes from the session and is **refused**
if sent in the body, along with `storage_key`, `source_url`, `entitlement_mode` and
`delivery_mode` — all owner-only. Append-only: this path creates, never overwrites.
Off by default. Enable per project with `configure { member_upload_enabled: true }`.
```javascript
const res = await sapi.callUpload('/execute/gated-files/put-upload', {
file: fileInput.files[0],
title: 'Crosswalk, iteration 1' // optional, shown back by list-mine
});
if (!res.data.success) { console.warn(res.data.error); return; }
const f = res.data.result; // { file_id, filename, size_bytes }
```
Check `file.size` before calling — see the note under "Calling SAPI as a signed-in member".
`list-mine` is the read counterpart: the files this **organisation** may reach, not just
the caller's own. Every row is put through the same entitlement check `download` runs, so
it can never list a file `download` would then refuse. It never returns `storage_key`.
```javascript
const res = await sapi.call('POST', '/execute/gated-files/list-mine', { limit: 50 });
const files = res.data.success ? res.data.result.files : [];
// [{ file_id, filename, content_type, size_bytes, title, added_by, source, created_at }]
```
### Anti-patterns — never do these for member files
- ❌ Uploading member-only files as normal PAPI assets — they land on the **public CDN**;
anyone with the URL can download them forever, whatever gate the page has.
- ❌ Using `file-downloads` for paid/sensitive content — `verify-token` returns the public
CDN URL, which afterwards works without any token.
- ❌ Embedding a static download token in page JS — everyone who views source has it.
gated-files needs no token in the page: the member's **session is the access**.
## Member Self-Profile — `account/get-me`
A signed-in member viewing their own record — "My Account", order history, membership
status — is a solved problem. Do **not** build it by querying MAPI from the browser and
filtering client-side.
The `account` integration resolves the identity **server-side from the verified session**.
The browser never sends an email, an id, or any other identifier, so there is nothing for
a visitor to tamper with. Each configured source declares an explicit **field allowlist**;
anything not listed is never returned, so a private column cannot leak by accident.
Works with a verified **Visitor Auth** session and with a **Tenant Auth** member session.
### Configure once (MCP)
```
execute_integration(project_id: 12345, service: "account", endpoint: "set-profile",
input: {
enabled: true,
require_verified: true,
identity: { from: "session_email" },
sources: [
{
key: "me",
entity: "members",
match: { field: "email", from: "session_email" },
fields: ["id", "name", "email", "created_at"], // allowlist — REQUIRED
cardinality: "one",
not_found: "null"
},
{
key: "orders",
entity: "orders",
match: { field: "member_email", from: "session_email" },
fields: ["id", "total_cents", "status", "created_at"],
cardinality: "many"
}
]
})
```
- `cardinality`: `one` → object, `many` → array.
- `not_found`: `null` (default) or `error`.
- Child records can be scoped to the matched parent instead of the session email — useful
for order lines belonging to the member's own orders.
- `get-profile` reads the current configuration back; `remove-profile` clears it.
### Browser flow
```javascript
const sapi = WP.sapi(PROJECT_ID);
// Tenant members only. For Visitor Auth the verified session is enough — omit this line.
sapi.setBearer(localStorage.getItem('tenant_token'));
const res = await sapi.call('POST', '/execute/account/get-me', {});
if (!res.data.success) {
console.warn(res.data.error, res.data.upstream_status); // see Shared Member Content
return;
}
const data = res.data.result; // { verified: true, email, me: {...}, orders: [...] }
```
Without a verified session the call returns **401 `"A verified visitor session is
required"`** — it fails closed, it does not return an empty profile.
`update-profile` writes back to the same record, restricted to the fields the profile
allows. The member can only ever reach their own row.
### Anti-patterns
- ❌ Querying a MAPI entity from the browser and filtering on the member's email in JS —
the unfiltered rows already reached the browser.
- ❌ Passing the member's email or id in the request body so the server can look them up —
whatever the browser sends, a visitor can change. The session is the identity.
- ❌ Omitting the `fields` allowlist to "get everything" — it is required precisely so a
later column addition cannot silently start leaking.
## Shared Member Content — `records`
`account/get-me` answers "show me **my** row". A different question is "show **our** rows":
a team wiki, an internal project log, shared documentation that several named members read
together. That is what the `records` integration is for.
It reads a MAPI entity under the identity the session already established, and the entity's
`policy_json` decides which rows come back and which fields are stripped. The browser never
sends an identity, so there is nothing to tamper with.
> **New (September 2026).** Verified end-to-end on 1 September 2026: two members of the
> same tenant read the same rows, a member of another tenant sees none, a cross-tenant
> record returns 403, and hidden fields stay out of the response. It is new, so treat the
> first page you build on it as you would any new feature — check it from a real member
> login before you tell anyone their content is private.
### Requirements
- The entity **must** carry a `policy_json`. An entity without one returns **404** — that is
deliberate: an ungoverned entity would hand back every row.
- Keep `public_read: false`. The policy decides access; `public_read` is ignored once a
policy exists.
- Read-only. Members cannot write through this route.
- **Not SSR.** See the SSR warning earlier in this document — the render cache is shared
across visitors, so gated content must be fetched client-side.
### Policy for shared content
All members of one organisation share the same rows — no per-row ownership:
```json
{ "owner_field": "tenant_code",
"owner_scope": "tenant",
"rules": {
"read": {"verified":"own","project":"all"},
"list": {"verified":"own","project":"all"} },
"fields": { "verified": { "hide": ["internal_note"] } } }
```
Every member of that tenant sees the tenant's rows; a member of another tenant sees none.
Requires **Tenant Auth** (`wst_`) — plain Visitor Auth gives a per-person identity and
cannot express "our rows".
### Browser flow
```javascript
const sapi = WP.sapi(PROJECT_ID);
sapi.setBearer(localStorage.getItem('tenant_token')); // once per page load
const res = await sapi.call('POST', '/execute/records/list', {
entity: 'iteration_log',
filter: { published: 1 }, // optional, equality only
sort_by: 'id', sort_order: 'ASC',
per_page: 50, offset: 0
});
if (!res.data.success) {
// A denied read arrives as HTTP 200 with success:false — see below.
console.warn(res.data.error, res.data.upstream_status);
return;
}
const data = res.data.result; // { entity, data: [...], pagination: {...} }
```
`records/get` takes `{ entity, id }` and returns a single record.
> **Check `j.success`, not the HTTP status.** The SAPI execute route only returns a real
> HTTP error for things it rejects itself — no session, missing CSRF (401/403). Anything
> the integration refuses (403 not your row, 404 unknown or ungoverned entity, 422 a
> blocked filter) comes back as **HTTP 200** with `success: false`, an `error` string and
> an `upstream_status`. Code that branches on `res.ok` or `res.status` treats a permission
> denial as a success and renders an empty page with no explanation — the worst possible
> outcome for a member area, because it looks like "no content" rather than "access
> denied". This applies to every `/execute/` call, `gated-files` and `account` included.
### What the guards refuse, and why
- **Filtering or sorting on a field the policy hides → 422.** Hiding a column keeps it out
of the response, but filtering on it would let a member binary-search the value from the
rows that come back. Both are blocked.
- **Filtering on the `owner_field` → 422.** Scope is set by the policy, never by the client.
- **A record belonging to another tenant → 403.** An unknown record, an unknown entity, or an
ungoverned entity → **404**, all indistinguishable from outside.
- `per_page` is capped at 200.
### Anti-patterns
- ❌ Setting `public_read: true` "just to get it working" — the content becomes readable at
`/mapi/public/{projectId}/{entity}` by anyone, and a login gate in the page protects
nothing because it runs in the browser.
- ❌ Rendering shared member content with `<!--#wps-mapi -->` — the SSR cache is shared per
page, so the first member's data would be served to everyone.
- ❌ Checking the policy as the project owner and concluding it works — an owner bypasses row
scoping entirely. Verify from a real member session.
## AI Continuity — Staying on Track Across Sessions
AI assistants typically lose all context when a conversation ends.
WebsitePublisher solves this with infrastructure layers that preserve knowledge:
### Skills (this document)
You are reading a skill right now. Skills are structured instructions that teach AI
how to work with the platform — which patterns to follow, which mistakes to avoid,
and which tools to use. Without skills, every AI session would rediscover
how the platform works from scratch.
**Always call `get_skill` at the start of a session.** It ensures you follow current
best practices, regardless of which AI platform the user is on.
### Design Context (site_context integration)
Design decisions should be **saved immediately** when made — not at the end of a
session when they might be forgotten. Use `site_context` as a living design brief
that any AI session can pick up.
`site_context` stores **design tokens only**: `color_palette`, `fonts`,
`style_notes`, `locale`. Build status, page progress, and to-dos do **not** belong
here — that is what Task Tracking (TAPI, next section) is for. Sending any other
field returns `"No valid fields provided"`.
**Save after every design decision** — writes are a **deep merge**: only the fields
you send are overwritten, everything else is preserved:
```
execute_integration(
service: "site_context",
endpoint: "set-context",
input: {
color_palette: { primary: "#2D5016", secondary: "#F5F0E8", accent: "#B8860B",
background: "#FAF7F2", text: "#1A1A1A" },
fonts: { heading: "Playfair Display", body: "Inter" },
style_notes: "Warm, artisanal, Japanese-inspired minimalism",
locale: "en"
}
)
```
Field reference: `color_palette` keys are `primary`, `secondary`, `accent`,
`background`, `text` (hex strings). `fonts` keys are `heading` and `body`
(font family names). `style_notes` is free text, max 500 chars. `locale` is
ISO 639-1 (`"nl"`, `"en"`, `"de"`).
**Sections** — a project with more than one visual style (e.g. public site vs admin
panel vs email templates) stores each as a named section via the optional `section`
parameter (`"frontend"`, `"admin"`, ...). Without it, reads and writes target
`"default"`. Max 10 sections per project. The `"default"` section is also included
in the `get_project_status` response.
**Retrieve at the start of every session:**
```
execute_integration(service: "site_context", endpoint: "get-context", input: {})
```
Pass `section: "all"` to get every section as a keyed object.
**List which sections exist:**
```
execute_integration(service: "site_context", endpoint: "list-sections", input: {})
```
**Delete context** — ⚠️ omitting `section` deletes **ALL** sections for the project.
Always pass the section explicitly:
```
execute_integration(service: "site_context", endpoint: "delete-context",
input: { section: "admin" })
```
This is the single most important continuity tool. Without it, a new AI session
has to ask the user to re-explain every design choice.
### Task Tracking (TAPI)
Track anything that outlives one conversation: a multi-session build, a decision and
why it was taken, a bug that is not fixed yet, what a client asked for last month. Each
task has a slug, status and history, and all of it is visible in the next session — with
this assistant or a different one entirely.
This is the platform's answer to a model that forgets. Write to it as you go rather than
at the end: the value is in being able to answer *"where were we"* and *"why did we do it
that way"* months later, and that only works if the reasoning was recorded when it was
still fresh.
**Create tasks for each build phase:**
```
tasks(operation: "create", slug: "homepage-build", title: "Build homepage with hero + features")
tasks(operation: "create", slug: "shop-pages", title: "Shop overview + product detail pages")
tasks(operation: "create", slug: "contact-form", title: "Contact form with Resend email")
tasks(operation: "create", slug: "admin-dashboard", title: "Admin panel with auth + CRUD")
```
**Update progress as you work:**
```
tasks(
operation: "add_history",
slug: "homepage-build",
type: "progress",
status: "done",
completion_pct: 100,
summary: "Homepage live: hero section, 3 feature cards, testimonials, CTA"
)
```
**Start of next session — check what's done and what's next:**
```
tasks(operation: "list", status: "in_progress") # What's being worked on
tasks(operation: "list", status: "open") # What hasn't started yet
```
> One tool, many operations: `list`, `get`, `history`, `create`, `add_history`, `update`,
> `delete`, `search`, `export`. The old separate names (`create_task`, `list_tasks`,
> `add_task_history`, …) still dispatch but are **legacy** — always use `tasks`.
This gives every AI session — regardless of platform — a shared understanding of
where the project stands. The user doesn't have to re-explain what was already built.
### Scheduled Tasks (AAPI)
Websites sometimes need automated actions: publish a page at a specific time,
send a weekly email digest, update data records on a schedule. The AAPI layer
handles this without requiring the AI or the user to be present.
Available via: `create_scheduled_task`, `list_scheduled_tasks`
### Visual Editor (WPE)
The user does not need to start a new AI conversation for every small change.
The Visual Editor lets them update images, reorder content, and adjust styles
directly in their browser — at any time, without AI involvement.
These layers ensure that the **quality and consistency of the website do not depend
on which AI session is active.** The platform remembers — the AI doesn't have to.
---
## API Quick Reference
### Base URLs
```
Pages & Assets: https://api.websitepublisher.ai/papi/
Entities & Data: https://api.websitepublisher.ai/mapi/
Forms & Sessions: https://api.websitepublisher.ai/sapi/
Vault: https://api.websitepublisher.ai/vapi/
Integrations: https://api.websitepublisher.ai/iapi/
Dashboard: https://api.websitepublisher.ai/dapi/
```
### Key PAPI Endpoints
```
GET /papi/projects List projects
POST /papi/projects Create project
GET /papi/project/{id}/pages List pages
POST /papi/project/{id}/pages Create page
PUT /papi/project/{id}/pages/{slug} Update page
DELETE /papi/project/{id}/pages/{slug} Delete page
POST /papi/project/{id}/assets Upload asset
GET /papi/project/{id}/pages?type=fragment List fragments
```
### Key IAPI Endpoints
```
POST /iapi/project/{id}/{service}/{endpoint} Execute integration
# Examples:
POST /iapi/project/{id}/leads/submit-lead Store a lead
POST /iapi/project/{id}/leads/get-leads Retrieve leads (authenticated)
POST /iapi/project/{id}/leads/update-status Update lead status
POST /iapi/project/{id}/resend/send-email Send email via Resend
POST /iapi/project/{id}/mollie/create-payment Create Mollie payment
POST /iapi/project/{id}/site_context/set-context Save design context (deep merge)
POST /iapi/project/{id}/site_context/get-context Get design context (section or "all")
POST /iapi/project/{id}/site_context/list-sections List stored context sections
POST /iapi/project/{id}/site_context/delete-context Delete a section (no section = ALL)
POST /iapi/project/{id}/capability_requests/submit-request Report platform gap (last resort)
POST /iapi/project/{id}/product-catalog/bulk-upsert-products Bulk import (up to 500)
POST /iapi/project/{id}/tracer/start Start debug trace session
POST /iapi/project/{id}/tracer/logs Read trace entries
POST /iapi/project/{id}/pdf_document/generate Branded PDF from content blocks
POST /iapi/project/{id}/pdf_document/render-template Own HTML template (PAPI asset) → PDF; data = root context; store:false → base64
# Email Archive (service: "email_archive" — the user's own archived mail):
POST /iapi/project/{id}/email_archive/list-archives Archives + source counts (resolve archive_id FIRST)
POST /iapi/project/{id}/email_archive/search Keyword/semantic/hybrid search; archive_id required
POST /iapi/project/{id}/email_archive/get-message One message incl. body_plain
POST /iapi/project/{id}/email_archive/get-thread Whole thread, chronological (metadata only)
POST /iapi/project/{id}/email_archive/list-attachments Attachments of one message (index, name, size)
POST /iapi/project/{id}/email_archive/get-stats Counts, size, date range, per-folder
POST /iapi/project/{id}/email_archive/set-state Mark handled / kept / todo
POST /iapi/project/{id}/email_archive/draft-reply Suggested reply text (never sends)
POST /iapi/project/{id}/email_archive/context-feed LLM-ready rolling summary + recent messages
# Calendar & Booking (service: "calendar" — 15 endpoints, all datetimes UTC):
POST /iapi/project/{id}/calendar/upsert-calendar Create/update a calendar (timezone for rendering)
POST /iapi/project/{id}/calendar/list-calendars List calendars
POST /iapi/project/{id}/calendar/delete-calendar Delete calendar + events (refuses while resources attached)
POST /iapi/project/{id}/calendar/upsert-event Create/update event (start_at/end_at UTC)
POST /iapi/project/{id}/calendar/delete-event Delete event
POST /iapi/project/{id}/calendar/list-events Events overlapping [from, to)
POST /iapi/project/{id}/calendar/upsert-resource Bookable resource: type chair|table|room, capacity, config
POST /iapi/project/{id}/calendar/list-resources List resources (filter type/active)
POST /iapi/project/{id}/calendar/delete-resource Delete resource (refuses with upcoming bookings)
POST /iapi/project/{id}/calendar/set-availability Rules per resource: weekdays/slot_minutes/exceptions/vacations
POST /iapi/project/{id}/calendar/get-slots Free slots (tables/chairs) or nights (rooms), local+UTC times
POST /iapi/project/{id}/calendar/book Transactional claim — double bookings impossible; returns cancel_token
POST /iapi/project/{id}/calendar/cancel-booking Cancel via cancel_token (visitor) or booking_id (admin)
POST /iapi/project/{id}/calendar/list-bookings Bookings with filters + pagination
POST /iapi/project/{id}/calendar/update-booking-status pending|confirmed|completed|cancelled|no_show
```
### Calendar & Booking — usage notes
- **One model, three verticals**: appointments = `chair` (slot + service duration), restaurant =
`table` (slot + `seating_minutes`, `min_party`/`max_party`), hotel = `room` (night granularity,
`checkin`/`checkout` dates, `min_stay_nights`). Configure per resource via `config`.
- A booking automatically creates an event on the resource's calendar; cancelling flips both to
`cancelled`. Bookings with a `visitor_email` get a confirmation/cancellation email automatically.
- **Visitor-facing booking** works today via a SAPI form with an `iapi` action:
`action: { type: "iapi", service: "calendar", endpoint: "book", input_template: { resource_id: 12,
start_at: "{{fields.start_utc}}", end_at: "{{fields.end_utc}}", visitor_name: "{{fields.name}}",
visitor_email: "{{fields.email}}", party_size: "{{fields.party}}", source: "web" } }`.
Render available options server-side or fetch them owner-side; anonymous browser calls to
`get-slots` are not enabled yet.
### Key SAPI Endpoints (visitor-facing, no bearer token)
```
GET /sapi/project/{id}/session Start or resume session
GET /sapi/project/{id}/csrf/refresh Refresh CSRF token
POST /sapi/project/{id}/form/submit Submit form data
POST /sapi/project/{id}/form/upload Upload image (multipart)
POST /sapi/project/{id}/auth/request Request magic link/code
POST /sapi/project/{id}/auth/verify Verify code
GET /sapi/project/{id}/auth/status Check auth status
```
### Lead Capture
Form submissions with `action: {"type": "leads"}` are stored in the platform's
built-in lead capture — no integration setup required.
**Retrieve leads via MCP tool:**
```
leads_get_leads → project_id (+ optional: status, form_name, page, per_page)
```
**Retrieve leads via HTTP (for dashboard pages / browser JavaScript):**
```
POST /iapi/project/{id}/leads/get-leads
Authorization: Bearer {wps_token}
Content-Type: application/json
Body: {"page": 1, "per_page": 25}
Optional filters: status (new/contacted/converted), form_name, date_from, date_to
```
**Important:** Leads are always authenticated — there is no public URL.
Never ask for routing files to find the leads endpoint — the URL above is canonical.
**Configure lead capture on a form:**
```json
{
"form_name": "contact",
"actions": [{"type": "leads"}],
"required_fields": ["name", "email"]
}
```
---
## For Platform Developers
If you are working on the WebsitePublisher.ai platform itself rather than building
a customer website, a separate development skill is available with internal conventions,
TAPI task tracking workflow, and infrastructure reference:
```
https://www.websitepublisher.ai/skills/websitepublisher-dev/SKILL.md
```
### Full Documentation
https://www.websitepublisher.ai/docs
### MCP Setup (for Claude Desktop, Cursor, Windsurf, GitHub Copilot)
https://www.websitepublisher.ai/docs/mcp
```
**After upload via the editor** the `src` is automatically replaced by the CDN URL
(`cdn.websitepublisher.ai/custom/wid{id}/images/...`).
#### Common placeholder dimensions
| Usage | Dimensions |
|---|---|
| Hero wide | 1200x675 |
| Photo 4:3 | 800x600 |
| Portrait | 600x800 |
| Nav logo | 240x48 |
| Team card | 600x520 |
#### ⚠️ Image performance — mandatory rules
Every `
```
**Never do this:**
```html
```
**Impact:** A page with 11 images missing `loading="lazy"` fires 11 simultaneous CDN requests on page load. On mobile (slower network, in-app mail browsers), this causes blank pages and multi-second load delays. Adding lazy loading reduced this to 1-2 eager requests with the rest deferred.
### Assets — Images, CSS, JS, and Files
Assets are files stored on the WebsitePublisher CDN (`cdn.websitepublisher.ai/custom/wid{id}/...`).
Use `upload_asset` to add images, stylesheets, JavaScript, fonts, PDFs, and other static files
to a project. Assets are served globally with caching — fast and reliable.
**Three ways to provide content:**
| Parameter | Use for | Example |
|---|---|---|
| `source_url` | Import from a durably hosted public URL — the server fetches it | Images on an existing website, a stock-photo CDN, a client's current hosting |
| `content` | Base64-encoded binary data | Images generated locally or received as base64 |
| `content_text` | Plain text content (saves tokens vs base64) | CSS, JS, JSON, SVG, HTML, XML, MD files |
Always provide exactly **one** of the three. Never combine them.
#### Importing Images from External URLs
The `source_url` parameter is the easiest way to bring images into a project. The server
fetches the file, validates it (HTTPS only, no internal IPs), and stores it on the CDN.
This works for **any public HTTPS URL** — not limited to any specific platform.
**Works well:**
- Migrating images from an existing website (WordPress, Wix, Squarespace, any CMS)
- Importing stock photos from Unsplash, Pexels, or similar services
- Pulling logos or assets from a client's current hosting
**Does NOT work — use `content` (base64) instead:**
- AI-generated image URLs (DALL·E, Midjourney and similar). These are temporary and
signed; the signature is lost when the URL is passed along, so the fetch returns 404.
- Google Drive and Google Photos links (`drive.google.com`, `lh3.googleusercontent.com`).
These need an authenticated session — the server has none, so it gets a 404 even when
the file opens fine in your own browser.
- Any signed cloud-storage link with an expiring token in the query string.
- Files the user has on their own machine. Point them to the Files page in the dashboard,
then use `list_assets` to get the CDN URL.
In production these four categories account for the large majority of failed fetches, so
check the source before reaching for `source_url`.
**Example — import a single image:**
```
upload_asset(
project_id: 12345,
slug: "images/hero-photo.jpg",
source_url: "https://existing-site.com/wp-content/uploads/2025/hero.jpg"
)
→ CDN URL: cdn.websitepublisher.ai/custom/wid12345/images/hero-photo.jpg
```
**Example — batch import from an existing site:**
```
upload_asset(project_id: 12345, slug: "images/project-1.jpg", source_url: "https://old-site.nl/uploads/photo1.jpg")
upload_asset(project_id: 12345, slug: "images/project-2.jpg", source_url: "https://old-site.nl/uploads/photo2.jpg")
upload_asset(project_id: 12345, slug: "images/team-photo.jpg", source_url: "https://old-site.nl/uploads/team.jpg")
```
Then reference the new CDN URLs in your page HTML:
```html
```
**Rules:**
- `source_url` must be HTTPS — HTTP URLs are rejected
- Internal/private IP addresses are blocked (SSRF protection)
- Works for images (JPEG, PNG, WebP, GIF), PDF, fonts (.woff, .woff2, .ttf), and .ico files
- Set `overwrite: true` to replace an existing asset with the same slug
- The slug determines the CDN path — use descriptive names: `images/hero.jpg`, `images/team/jan.jpg`
- Alt text can be set via the `alt` parameter for images
**When migrating a website:** list all images on the old site first (via web fetch, sitemap,
or CMS tools), then upload each one with `source_url`. Update page HTML to reference the
new CDN URLs. The old site must remain accessible until all images have been imported.
#### Uploading Text-Based Assets
For CSS, JavaScript, JSON, SVG, and other text files, use `content_text` instead of base64
encoding. This is more token-efficient and easier to read:
```
upload_asset(
project_id: 12345,
slug: "//cdn.websumo.com/css/custom-styles.css",
content_text: "body { font-family: 'Inter', sans-serif; }"
)
```
#### Managing Existing Assets
| Action | Tool |
|---|---|
| List all assets | `list_assets(project_id: 12345)` |
| Read asset content | `get_asset(project_id: 12345, slug: "//cdn.websumo.com/js/app.js")` |
| Edit text asset in place | `patch_asset(project_id: 12345, slug: "//cdn.websumo.com/js/app.js", patches: [...])` |
| Replace asset | `upload_asset(project_id: 12345, slug: "images/old.jpg", source_url: "...", overwrite: true)` |
| Delete asset | `delete_asset(project_id: 12345, slug: "images/unused.jpg")` |
`get_asset` returns the current `version_hash` for optimistic concurrency on later edits. For binary assets larger than 1 MB, `content` is omitted — use the `url` field to download the file directly.
### Dynamic Data (MAPI) — When Entities Make Sense
**Use MAPI entities when content is managed independently of page design** — the
owner (or a different AI session) should be able to add, remove, or reorder items
without touching page HTML.
**Use MAPI + SSR for:**
| Content type | Entity name | Example fields |
|---|---|---|
| Menu items | `menuitems` | name, description, price, category, sort_order |
| Team members | `team` | name, role, bio, photo_url, sort_order |
| Services / offerings | `services` | title, description, icon, price, sort_order |
| Portfolio projects | `projects` | title, description, image_url, link, category, sort_order |
| Testimonials / reviews | `testimonials` | name, role, company, quote, photo_url |
| Blog posts | `posts` | title, slug, content, author, published_at, featured_image |
| FAQ items | `faq` | question, answer, category, sort_order |
| Events | `events` | title, date, location, description, registration_url |
| Products (showcase) | `products` | name, description, price, image_url, category |
**Use static HTML when:**
- Content is small and fixed (≤5 items that rarely change — e.g. 3 services on an about page)
- The page is a one-off (hero text, about narrative, single landing page)
- The owner will only update content through an AI session anyway
- It's page structure and layout (sections, containers)
**Don't over-engineer.** A restaurant with 8 menu items that change twice a year
does not need a MAPI entity + SSR template + admin panel. Static HTML with clear
structure is fine — the AI can update it in 30 seconds when the menu changes.
**The trigger for MAPI:** when you hear "I want to add/remove items myself" or when
items will grow beyond 10, or when multiple pages show the same data differently
(e.g. a shop overview AND a homepage featured section both pulling from products).
**How to build with MAPI — two tools, operation-based:**
Schema work goes through `entities` (operations: `list`, `create`, `update`, `delete`,
`schema`, `add_property`, `delete_property`). Data work goes through `records`
(operations: `list`, `get`, `create`, `update`, `delete`).
Property types: `varchar`, `text`, `int`, `datetime`, `tinyint`.
1. Define the entity:
```
entities(operation: "create", project_id: 12345, entity_name: "services",
properties: [
{ name: "title", type: "varchar", required: true },
{ name: "description", type: "text" },
{ name: "icon", type: "varchar" },
{ name: "price", type: "varchar" },
{ name: "sort_order", type: "int" }
],
public_read: true
)
```
⚠️ `public_read: true` makes the data **publicly readable** via
`/mapi/public/{projectId}/{entity}` — use it only for content that belongs on the
public site (menus, team, services). **Never** on personal or financial data
(customers, orders, loyalty). See **Data Access Control** below.
2. Create records:
```
records(operation: "create", project_id: 12345, entity_name: "services", data: {
title: "Web Design", description: "...", icon: "🎨", price: "From €499", sort_order: 1
})
```
`records(operation: "update", ...)` is partial — only provided fields change.
Add a column later with `entities(operation: "add_property", entity_name: "services",
property_name: "badge", type: "varchar")`; inspect the schema with
`entities(operation: "schema", entity_name: "services")`.
3. **Render with SSR (preferred — SEO-friendly):**
Use `` template tags in your HTML. The platform renders entity data
server-side before delivering the page, so search engines see full content immediately.
```html