Embeddable views
What this page is — tokens that let a partner's website frame one Papers view — generate a document, check its status, review it, or sign it — without an Orbit account.
What it is for — so an NDA request on your own site, a reseller's quote form or a counterparty's review can happen where that person already is, and land in your normal lifecycle.
The problem it solves — people who start a document request on another website are sent elsewhere to finish it, and many do not.
Route: /org/settings?tab=papers → Embeddable views · Permission: the organisation Papers
settings permission.
1. What it is
A token unlocks exactly one view on named partner origins:
| View | The partner can | Extra credential needed |
|---|---|---|
| Generate document | Pick one of your active types, fill its fields, submit a draft | — |
| Check status | Look up a submission by reference and email | — |
| Review & respond | Read, comment, suggest redlines, return or accept | The counterparty's emailed portal link |
| Sign | Complete the signing ceremony | The signer's emailed signing link |
Why review and sign need a second credential. The embed token sits in the partner page's HTML, so everyone visiting that page holds it. It identifies a site, never a person — so it can say "this site may frame our views", never "the bearer may read this contract". The personal link is passed alongside:
<iframe src="https://api.example-orbit.com/embed/papers/review?token=EMBED_TOKEN&portal=PORTAL_TOKEN"
style="width:100%;min-height:720px;border:0;" title="Review document"></iframe>
2. Why you would use it
- Requests arrive on your terms, from their site. A partner's quote form creates a real draft in your lifecycle.
- No licences for outsiders. Partners and counterparties need no Orbit login.
- Leaks are containable. One view per token, named origins, expiry, submission caps, instant revoke.
- Every request is auditable. History shows what each token did and where each request came from.
3. Step by step
- Embed token → choose the View.
- Name it after the partner and page.
- List Partner origins.
- Optionally a Maximum submissions and an expiry.
- Pick Scope — organisation-level types only, or a project.
- Copy the snippet — the token is shown once.
- Test in the Embed Sandbox (API Lab), then hand the snippet over.
4. Field reference
| Field | Rules | Refusal |
|---|---|---|
| View | One of the four | view must be one of: generate, status, review, sign |
| Name | The only way to recognise the token later | — |
| Partner origins | Required. partner.example means https://partner.example; *.partner.example allows every subdomain; a root domain does not cover its subdomains | frame_ancestors is required — the partner origins allowed to embed this view · frame_ancestors entries must be an origin or host… |
| Maximum submissions | Blank = unlimited; only document creation counts; reaching it marks the token exhausted | — |
| Expires in | Up to 180 days | expires_days must be at most 180 |
| Scope | Organisation types only, or a project's types plus organisation types — documents are created in that project | — |
What partners may see when something is wrong
| Message | Means |
|---|---|
| invalid or expired embed token | Expired or unknown |
| this embed token has been revoked | Revoked |
| this token does not grant the requested view | Wrong view |
| this origin is not on the token's frame-ancestors allowlist | The framing site is not listed |
| this embed link only works inside an allowed partner site… | Opened directly, not framed |
Two levels of enforcement
| Level | How | When |
|---|---|---|
| Browser-enforced (preferred) | A per-token frame-ancestors policy: unlisted sites cannot frame the view at all | FRONTEND_DIST_PATH is set on the API host |
| API-enforced | The page loads anywhere, but every data call from an unlisted site is refused | Otherwise |
When a partner submits
| Step | Result |
|---|---|
| 1 | A draft is created in your lifecycle, authored as the token's creator |
| 2 | The token's owner gets an in-app alert and the Papers - Embedded Form Submission email |
| 3 | The partner gets the Papers - Embedded Form Receipt email, with a reference for the status view |
| 4 | The request is recorded in the token's History, with its origin |
A blank email field still creates the document, but sends no receipt and allows no status lookup.
5. Worked example
A reseller, Fabrikam, wants to collect quotation requests under its own brand.
| Setting | Value |
|---|---|
| View | Generate document |
| Name | Fabrikam — quote page |
| Partner origins | https://quotes.fabrikam.example |
| Maximum submissions | 200 |
| Expires in | 90 days |
| Scope | Reseller Quotes project |
They test in the Embed Sandbox, adding the sandbox origin temporarily, then mint the real token. Fabrikam pastes
the snippet. Over a month, History shows 61 documents created, and 4 refusals from https://www.fabrikam.example
— the marketing site, not the quote subdomain, because a root domain does not cover subdomains. It was a staging
copy; the lead leaves it refused.
When Fabrikam's contract ends, the lead revokes the token. The page stops working at once.
6. The admin contract
| Must be true | Where | What breaks without it |
|---|---|---|
FRONTEND_DIST_PATH set on the API host | Operations | Only API-level enforcement; direct framing is not blocked |
API_PUBLIC_URL set | Operations | Snippets point at the wrong host |
| The embed email templates are installed | Communication Channels | No alert or receipt emails |
| Active, published types exist in scope | Type Designer | The generate view offers nothing |
| Tokens are reviewed and revoked | This screen | Stale partner access persists until expiry |
7. Downstream
| When… | Then |
|---|---|
| A partner submits | A draft appears in the scope's project |
| The cap is reached | The token shows exhausted; status checks still work |
| You revoke | Every page using it stops at once |
8. Don't confuse this with…
| Shared links | Share one sealed PDF with a person |
| Counterparty portal | The same review experience on Orbit's own domain |
| Intake forms | Your own marketing forms, not a partner's site |
9. Troubleshooting
| Symptom | Cause |
|---|---|
| The frame is blank on the partner site | The origin is not listed, or www versus a subdomain mismatch |
| Works in the sandbox, not on the partner site | The partner's exact origin is missing |
| expires_days must be at most 180 | Tokens last at most 180 days |
| Submissions stopped | The token is exhausted or expired |
| No receipt email | The partner left email blank, or the template is not installed |
| The token value is lost | It is never shown again — mint a new one and revoke the old |