Embedded views
What this page is — putting a Papers screen inside a partner's website in an iframe, and the two credentials that make that safe.
What it is for — so a partner's users can create, review or sign a Papers document without leaving the partner's site.
The problem it solves — sending people to another website to sign one document loses a share of them at the hand-off.
Route: /embed/papers/<view> framed on the partner's site · Permission: Papers module limits, defaults, integrations and signature-provider toggles.
to mint, list and revoke tokens
1. What it is
An embed token is a signed credential that says this partner site may frame this view of Papers. The frame is chromeless, with no Orbit navigation, so it sits inside the partner's page as if it belonged there.
| View | Label in the mint dialog | What the visitor does | What authorises the document |
|---|---|---|---|
generate | Generate document | Creates a document from a published type by filling in its fields | The embed token — the document lands as a draft |
status | Check submission status | Looks up something they submitted | Their reference plus the email they used |
review | Review & respond | The deal room — read, comment, suggest, send back, accept | The per-document portal token they were emailed |
sign | Sign | The signing ceremony | The signer's own signing link token |
The embed token authorises framing, never document access
An embed token sits in the HTML of a public website, so it identifies a site, never a person. For
review and sign, document access comes from the second credential in the query. For status, it
comes from the reference and email pair. An integration that assumes the embed token opens documents
either leaks or does not work.
2. Why you would use it
- Users finish what they start. Sending a customer away to another site to sign loses a share of them. Keeping the step in the partner's product keeps them.
- Partners generate documents without your staff. A franchise site can create a correctly structured agreement straight from your published type, with its real fields and validation.
- No second implementation to drift.
reviewandsignreuse the portal and ceremony, so there is no separate rule deciding who may read a document inside an iframe. - Tokens can be switched off. Every token is registered, so a partner relationship that ends can be cut off the same day.
3. Step by step
- Open Settings → Papers → Embeddable views (settings page).
- Mint a token: choose the view, the allowed origins, optionally a project, the expiry, and
for
generatea maximum uses quota. - Copy the iframe snippet now. The token value is never stored, so it cannot be shown again.
- Give the snippet to the partner. For
reviewandsign, the partner appends the portal or signing token of the specific document to the frame URL. - Watch the token's events list to see its use, and revoke it when the relationship ends.
4. Field reference
| Field | Required | Rule — exact messages |
|---|---|---|
| View | Yes | "view must be one of: generate, status, review, sign" |
| Allowed origins (frame ancestors) | Yes | Empty: "frame_ancestors is required — the partner origins allowed to embed this view". Each entry must be an origin or host: https://partner.example, partner.example, or *.partner.example for every subdomain. No path, query or credentials |
| Expires in (days) | No | Default 30, maximum 180 — "expires_days must be at most 180" |
| Maximum uses | No | Caps how many documents the token may create. Blank or 0 means no cap |
| Project | No | Restricts generate to one project's types |
How the origin rule is enforced
| Layer | What it does |
|---|---|
| API | Every public embed call checks the caller's Origin or Referer against the list. A mismatch is refused: "this origin is not on the token's frame-ancestors allowlist" (403) |
| Browser | When the API host serves the embed shell, it sends a per-token frame-ancestors security header, so the browser itself refuses other sites |
If your deployment serves the embed page from the static frontend rather than the API host, only the API check applies. The static host cannot vary its security header per partner.
Public rate limits
| Call | Per minute |
|---|---|
| Token check | 30 |
| Context, type schema, branding | 60 |
| Create document, status lookup | 20 |
5. Choosing the view
| You want the partner to… | Use | Watch out for |
|---|---|---|
| Let their users start an application or agreement | generate | Set maximum uses so a leaked snippet cannot flood you with drafts |
| Let applicants follow progress | status | The applicant must keep their reference and email |
| Negotiate inside their product | review | Portal tokens still expire (30 days by default) |
| Collect signatures inside their product | sign | Code verification still applies unless the request uses magic link only |
6. Worked example
Gatiro's reseller, Northwind Partners, wants its customers to request a Reseller order form and
sign it without leaving portal.northwind.example.
- The Gatiro admin mints a
generatetoken.- Allowed origins:
https://portal.northwind.example. - Expiry: 90 days. Maximum uses: 200.
- Allowed origins:
- Northwind places the iframe on their New order page. A customer fills in the form, and a draft order form appears in Gatiro's project, attributed to the embed token.
- The admin mints a second token for
sign, with the same origin and 90 days. - Once Gatiro finalizes the order and sends it for signature, Northwind frames the signing view with the signer's own link token. The customer signs inside Northwind's portal.
- A test from
staging.northwind.exampleis refused with the allowlist message. The admin adds*.northwind.exampleto a new token rather than loosening the production one. - When the reseller agreement ends, both tokens are revoked. Their frames stop working immediately.
7. The admin contract
| What must be configured | Otherwise |
|---|---|
A published type for generate | Nothing can be generated |
| Allowed origins exactly matching the partner's scheme and host | Frames are refused |
| The API public URL and built frontend path set in deployment | Browser-level framing protection is not sent; only the API check protects you |
Documents finalized and sent for signature for sign | There is no signing token to frame |
| Someone keeps the snippet at mint time | Mint again — it is shown once |
8. Downstream
- Documents created through
generateenter the normal lifecycle as drafts, with the same numbering, approvals and AI behaviour as any other document. - Every token call is logged in the token's events list.
- Branding shown inside the frame comes from the organisation's Papers branding.
9. Don't confuse this with…
| Customer portal | Your own signed-in site, not a frame in someone else's |
| Share links | A page you send, not a component in a page |
| API keys | Server-to-server access. Embed tokens are browser credentials for one view |
10. Troubleshooting
| Symptom | Cause |
|---|---|
| The frame is blank or refused | The host page's origin is not on the token's list (check https and www) |
review or sign loads but shows no document | The portal or signing token is missing from the frame URL (§1) |
status finds nothing | The reference and email do not match what was submitted |
| It stopped working | Expired, revoked, or the maximum-uses quota is exhausted |
| Mint refused | Origins empty or malformed, or expiry above 180 days |