Register an embed block

Overview

An embed block frames a page you host inside a customer’s Custral workspace. Registering one takes three things from you: the origin Custral frames, the URL template it loads, and the scopes your page needs to read the workspace. Custral reviews that declaration, and a workspace admin accepts the scopes when they install your module. By the end of this page your block will be in review, and you will know what a workspace does to install it.

You need an approved provider first. See Become a provider.

Before you start

Serve the page over https:// from an origin you control, such as https://embed.acme.com.
Let Custral frame it. A Content-Security-Policy: frame-ancestors or X-Frame-Options header that blocks Custral renders your block as an empty box. The portal can check this for you (step 4).
Implement the handshake if you ask for scopes. Your page posts custral:ready and receives its token in reply. See Embed blocks.

1. Create the block

Open the provider portal

Go to app.custral.com/provider.

Click New embed block

On Overview, or New embed under Embeds.

Name it

Give it a Key (a stable handle such as acme.overview-panel), a name and icon, and a description. The name and description are what workspace members see in the block picker.

The block opens on its own page with three tabs: Block, Embed and Parameters.

2. Put it in a module

A workspace installs a module, and installing is where the admin is shown the scopes your blocks ask for. Put every embed that requests scopes in one.

Create a module

In Modules, click Create Module and give it a key, a name and a description, e.g. “Acme panels”. A new module starts Private.

Assign the block

Back on the block’s Block tab, pick the module and click Save Settings.

Custral decides whether a module is listed. The module’s page states where it stands, and there is no status control in the portal:

Module state	Meaning
Private	Not listed for workspaces. Where every new module starts.
Unlisted	Not offered in the catalog. A workspace that opens your provider directly can still find and install it.
Public	Offered in the connections catalog to every workspace.

3. Declare the embed

Open the block’s Embed tab.

Field	What to enter	Rules
Origin	The site Custral frames, e.g. `https://embed.acme.com`	`https://` only. No path, query or trailing slash. Frozen once approved.
URL template	The page Custral loads, e.g. `https://embed.acme.com/panel?record={{record.id}}`	Must stay on the origin. Can change after approval.
What your panel may read	The scopes your page’s token carries	Leave empty and the frame gets no token at all. Frozen once approved.
Browser capabilities	Optional. `fullscreen`	Nothing is granted unless you ask. `clipboard-write` is accepted but not yet granted.
Minimum height	Optional. Pixels	Your page can still grow with `custral:resize`.

The template can use these placeholders. Each value is URL-encoded, and a value that isn’t available becomes an empty parameter.

Placeholder	Resolves to
`{{org.id}}`	The workspace
`{{user.id}}`	The viewer
`{{component.id}}`	This block instance
`{{record.id}}`	The open record, on a record page
`{{record.<propertyKey>}}`	That property’s value on the open record

Scopes an embed can ask for

An embed’s token reaches workspace data, never workspace credentials. So three scopes can never be declared: applications:manage and webhooks:manage (either would let your page mint a permanent key) and widget:identify (it vouches for who a customer’s visitors are).

Scope	Lets your page
`records:read` / `records:write`	Read, or create and update, records
`objects:read`	Read the object and property schema
`documents:read` / `documents:write`	Read, or create and update, documents
`conversations:read` / `conversations:write`	Read, or update and reply to, conversations
`property_agents:read` / `property_agents:write`	Read, or manage, property auto-fill agents
`tasks:read`	Read tasks
`usage:read` / `usage:write`	Read, or record, usage events

The token is accepted by /v1. Ask for the least you need. The installing admin sees the list, and the token is further narrowed to what the viewer can already do: a read-only member gets a token that cannot write.

4. Check it, then submit

Read the resolved URL

Once the declaration is valid, What Custral will actually request shows your template filled in with obviously fake ids. This is the line your reviewer reads.

Click Check my site allows framing

Custral requests the page and reads its framing headers. Your site refuses to be framed means it would render as an empty box; allow Custral as a frame ancestor and check again. Couldn’t tell is not a refusal and does not block review.

Click Save and submit for review

The block’s state changes to In review.

Review

A Custral reviewer answers three questions about the declaration:

Does the origin belong to your provider?
Are the scopes plausible for what the block does?
Can the URL template resolve anywhere other than the declared origin?

The block’s page and the portal Overview show where it stands:

State	Meaning
Private	Not submitted. Only you can see it.
In review	With Custral. No workspace can install it yet.
Not approved	The reviewer’s reason is shown on the Embed tab. Editing the declaration and saving puts it back in the queue.
Unlisted	Approved. A workspace that installs your module can add it to a page, but it is not offered in the catalog.
Public	Approved, and offered in the catalog to every workspace.

What changes after approval

You change	Result
Origin or scopes	The block drops back to Private and needs review again. It leaves the catalog until it is re-approved, and frames already open lose access on their next `/v1` call rather than when their token expires.
URL template path or query	Nothing. The resolved URL is still pinned to the approved origin, so ordinary releases need no review.
Name, description, capabilities, height	Nothing.

How a workspace installs it

The admin opens Settings → Integrations

Your module is listed on the Modules tab once Custral has listed both your provider and the module.

They click Install Module and review your scopes

An Install <module name> prompt lists what your blocks can read. A module whose blocks request no scopes installs straight through.

Members add your block to a page

It appears in the block picker alongside Custral’s own blocks.

Uninstalling the module stops every token your blocks were handed at once, not when they expire.

Troubleshooting

Symptom	Cause	Fix
Save and submit for review is disabled	The declaration has problems, listed under Not ready to submit	Fix every listed problem. They are all shown at once.
”The URL template has to stay on the origin you declared.”	The template’s host differs from the origin, or puts a placeholder in the host	Keep placeholders in the path or query. `https://{{org.id}}.acme.com` is refused.
”One of those scopes can never be granted to an embed.”	You picked a credential or identity scope	Remove it. See Scopes an embed can ask for.
Your site refuses to be framed	Your server sends `X-Frame-Options` or a `frame-ancestors` policy that excludes Custral	Allow Custral’s origin in `frame-ancestors`, then check again.
The block went back to Private	You changed the origin or the scopes after approval	Expected. It is back in review.
A workspace can’t find your module	Your provider or the module isn’t listed yet	New providers and new modules both start hidden. Contact support when a block is approved and you are ready to be listed.
A workspace can’t find your block	The module isn’t installed, or the block isn’t approved yet	Check the block’s state in the portal, then ask the admin to install the module.
Your page gets no token	The declaration has no scopes, or the page never posted `custral:ready`	Declare a scope, and attach your `message` listener before posting. See The handshake.
A write returns `insufficient_scope` for some viewers	The token is narrowed to the viewer’s own access	Expected. Handle it as read-only for that viewer.

Embed blocks: the handshake, the token, and reading rows
Become a provider: the portal and developer access
Build for other workspaces: applications vs providers vs embeds
Embed block: the version customers configure with a pasted URL

Get started

Manage your integration

Build for other workspaces

Register an embed block

Overview

Before you start

1. Create the block

2. Put it in a module

3. Declare the embed

Scopes an embed can ask for

4. Check it, then submit

Review

What changes after approval

How a workspace installs it

Troubleshooting

​Overview

​Before you start

​1. Create the block

​2. Put it in a module

​3. Declare the embed

​Scopes an embed can ask for

​4. Check it, then submit

​Review

​What changes after approval

​How a workspace installs it

​Troubleshooting

​Related

Overview

Before you start

1. Create the block

2. Put it in a module

3. Declare the embed

Scopes an embed can ask for

4. Check it, then submit

Review

What changes after approval

How a workspace installs it

Troubleshooting

Related