Sharing

How share links work

A share link is a public URL for one diagram:

No account needed. Anyone who has the link can view the diagram.
Your access, not more. The diagram is drawn with the access you, the person who shared it, have. If your access is revoked, your links stop working too.
Revocation is immediate. A revoked or expired link stops working at once; nothing is cached that outlives it.
It opens your workspace's page. On kumo.io a link looks like https://kumo.io/@<workspace-address>/share/<token>; on a self-hosted installation it is your installation's address followed by /share/<token>.
The link is shown once. Kumo.io stores only a fingerprint of it, so copy it when you create it. If you lose it, create a new one.

Someone who opens a link that was revoked, has expired or never existed sees the same page: This Share Link Isn't Available. Kumo.io doesn't reveal which of the three it was.

Create a share link

Open the diagram and choose Share in the toolbar.
In Share This View, pick an expiry under Expires: Never, In 1 hour, In 24 hours, In 7 days or In 30 days.
Choose what the link shows: Share Latest follows the diagram, so the link always shows its newest version. Share This Snapshot pins the link to the snapshot you're looking at; it never changes.
Copy the link from the box that appears (Copy this link now — it is shown exactly once.) with Copy Link, then Dismiss.

Creating a link needs a role that can manage the workspace. If yours can't, the Share control is locked with Your role doesn't allow this.

Manage and revoke links

The Share panel lists every link for the diagram: whether it's Live latest or a Pinned snapshot, when it was created, when it expires, and whether it has been revoked.

To stop a link working, choose Revoke next to it, then Revoke Link to confirm. You can list and revoke links on any plan, so you can always wind sharing down after a downgrade.

What viewers see

The share page shows the diagram on its own, with Zoom In, Zoom Out and Reset View controls; viewers can also drag to pan and scroll to zoom. Viewers can't open resources, see other diagrams, or reach anything else in your workspace.

Embed a diagram in another page

After creating a link, choose Copy Embed to copy ready-made markup for an <iframe> that shows the shared diagram:

<iframe src="<your share link>" width="960" height="600" style="border:0" title="Kumo.io Diagram"></iframe>

Paste it into any page that allows iframes, such as a wiki or an internal portal. The embedded diagram follows the same rules as the link: it expires, revokes and redacts exactly as the link does.

Embedding through the API

The API also serves a share link in two forms for building your own pages:

Request	Returns
`GET /share/{token}`	The diagram itself. Add `?format=png` or `?format=pdf` for those formats; SVG is the default.
`GET /embed/{token}`	A small page that scales the diagram to fit an iframe. It takes the same `format` values; for PDF it shows a download link instead.

Both answer every unknown, revoked or expired link with the same "not found" response, and both tell browsers not to cache the result. The embed page is API-only: the app doesn't link to it.

On a self-hosted installation, embedding is allowed from any site by default. To allow it only from your own sites, set KUMO_EMBED_FRAME_ANCESTORS to a space-separated list of the origins that may embed it.

Create links through the API

With an API token, manage a diagram's links at /v1/accounts/{accountId}/workspaces/{workspaceId}/environments/{environmentId}/views/{viewId}/shares:

Request	What it does
`POST …/shares`	Creates a link and returns it with its `token`, once. Send `viewRevisionId` to pin a snapshot (omit it to follow the latest) and `expiresAt` (an ISO 8601 time) to set an expiry.
`GET …/shares`	Lists the diagram's links, without their tokens.
`DELETE …/shares/{shareId}`	Revokes a link.

See How do I authenticate to the API?

Which plans include sharing

Public share links are part of the Team, Business and Enterprise plans on kumo.io, and of Enterprise (Licensed) on a self-hosted installation. They aren't part of a trial.

If your account no longer includes sharing, your existing links stop resolving, and they work again if you upgrade. When a plan locks the Share control, selecting it opens an upgrade panel.

Share with people in your account

To share a diagram with people in your account instead of by link:

Open the diagram and choose Share in the toolbar.
At the bottom of the panel, under Share With People, pick a member or a role under Choose a member or role…, then choose Share.

The panel lists the people and roles the diagram is shared with. A role share reaches everyone who holds that role in your account, now or later.

There is no link to pass on. The people you share with sign in and open the diagram from Shared With Me: choose Go to Shared With Me in the command palette. They see the diagram's latest snapshot as you see it, with Zoom In, Zoom Out and Reset View, even if they can't open the diagram's workspace. Like a share link, it is drawn with your access: if you lose access to the workspace, everything you shared from it closes.

To stop sharing, choose Remove next to a person or role, then Stop Sharing. It takes effect the next time they open it. Sharing and removing are recorded in the audit log.

Sharing with people needs the Business or Enterprise plan and a role that can manage the workspace. If your plan doesn't include it, selecting the control opens an upgrade panel. You can still see and remove existing shares on any plan.

Only members of your account can be shared with. To share with someone outside it, use a share link, or invite them to your account.

Request	What it does
`POST …/views/{viewId}/access-grants`	Shares the diagram. Send `{"grantee": {"kind": "user", "userId": "…"}}` or `{"grantee": {"kind": "role", "roleId": "…"}}`.
`GET …/views/{viewId}/access-grants`	Lists who the diagram is shared with.
`DELETE …/views/{viewId}/access-grants/{grantId}`	Stops sharing with that person or role.
`GET /v1/accounts/{accountId}/shared-views`	The diagrams shared with you.
`GET /v1/accounts/{accountId}/shared-views/{grantId}/render`	One of them, drawn. Add `?format=png` or `?format=pdf`; SVG is the default.

… is /v1/accounts/{accountId}/workspaces/{workspaceId}/environments/{environmentId}.