# Sharing & links (https://systemhub.com/docs/concepts/sharing-and-links)

> Part of systemHUB Docs · Connect: Settings → AI Gateway in systemHUB · Auth: OAuth (scoping is workspace-level today — see Getting started) · MCP tools: 48 · Full corpus: https://systemhub.com/llms-full.txt

systemHUB documents can be reached two ways, and an agent should know which one it's handing out. They behave very differently.

## The two link types

| | App link | Share link |
|---|---|---|
| **Who can open it** | Logged-in members with access to that document | **Anyone with the URL — no login** |
| **What it shows** | The document in the systemHUB app | The **published** version, as machine-readable JSON |
| **Respects roles/visibility** | Yes — same access model as everything else | No — the link itself is the access |
| **Best for** | Team members working inside systemHUB | External contractors, auditors, clients — or **feeding a document to an AI that isn't connected via MCP** |

## App links

A regular link to a document inside the app. Opening it requires the person to log in and have access (via role or direct assignment — see [Roles & seats](/docs/concepts/roles-and-seats)). If they can't see the document in systemHUB, the link won't show it to them.

**An agent can construct an app link** from the workspace alias and the document UUID (which every tree, search, and details response carries):

```
https://{alias}.systemhub.com/systems/{uuid}     ← Systems
https://{alias}.systemhub.com/policies/{uuid}    ← Policies
https://{alias}.systemhub.com/trainings/{uuid}   ← Trainings
```

This also works in reverse: when a user pastes an app URL at you, the UUID in it is the same UUID the MCP tools address — extract it and call `get_system_details` (or the matching section's tool) directly. Caveats: this form **requires login** and access to the document, and the app won't error on a malformed UUID until after login — so treat a constructed link as "the right address," not proof the document exists.

> **Sending it to someone without a login?** Add the share code to make it public — see [the human-readable share link](#the-human-readable-share-link-use-this-one-for-people) below. (Both forms were surfaced by SYSTEMologists in the field.)

## Share links

A share link is a public URL for one document. Generate or retrieve one with:

```
→ get_document_share_link { "documentId": "7d4f2a90-…", "topicType": "system" }
```

Key behaviours:

- **Designed for no-login access.** The intent is that anyone holding the URL can fetch the published version as machine-readable JSON — the lightest-weight way to hand one process to an outside party or an AI without an MCP connection.
- **It reuses an existing share code** when the document already has one, and generates one if missing. Calling it twice doesn't create two links.
- ⚠️ **Share codes are not unique per document.** **Duplicating a document copies its share code**, so the copy and the original share one code (reported and reproduced across two document pairs, 4 Aug 2026). If you're building an index keyed on share codes, key on the document UUID instead — a share code can point at more than one document. Two code formats are also in circulation (longer codes on older documents, shorter on newer), so don't validate them by shape.
- **It shows the published version only** — unpublished edits stay private until published (see [Document lifecycle](/docs/concepts/document-lifecycle)).
- Generating one requires SHARE permission on that document type.

> ⚠️ **Known issue (verified 28 Jul 2026):** fetching the raw `api.systemhub.com/...` share URL from outside returns **403 "Company not found"** — that endpoint cannot resolve the workspace from the bare URL. Use the human-readable form below instead, which works.

## The human-readable share link (use this one for people)

Take the share code from `get_document_share_link` and put it on the **app host**, qualified by your workspace alias:

```
https://{alias}.systemhub.com/systems/{uuid}/{shareCode}
https://{alias}.systemhub.com/policies/{uuid}/{shareCode}
https://{alias}.systemhub.com/trainings/{uuid}/{shareCode}
```

**Verified 4 Aug 2026: this renders the published document in a browser with no login**, in a clean session — title, Overview and Details. A wrong or missing share code returns 404, so the code is doing the work, not an existing session.

- `{alias}` is your **company alias** — your systemHUB subdomain, the part before `.systemhub.com` (the same value used as the OAuth Client ID; find it in Settings → AI Gateway).
- `{uuid}` is the document ID, present on every tree, search and details response.
- `{shareCode}` is the trailing path segment of the `shareLink` returned by the share-link tool (or the `shareLink` field on `get_*_details`).

Two behaviours worth knowing when you construct or inspect these links:

- **The app rewrites to a guest route.** Opening the link lands on `/{section}/guest/{uuid}/{shareCode}?company={alias}` — the alias carried explicitly. That's expected; share the short form and let the app do the rewrite.
- **The section segment is not validated.** A system's UUID and code requested under `/policies/` still renders the system (reported 7 Aug 2026). So don't infer a document's section from the URL it was shared under — use `discriminator` on the document itself.

**This is the link to give a human.** It needs no login and no seat, which makes it the right answer for a contractor, an auditor, a client, or a team member on their phone.

> ⚠️ **Agents: you cannot fetch this form.** The share view is a client-rendered app, so a plain HTTP request (curl, an agent's fetch tool, a link unfurler, a preview bot) gets the JavaScript shell — *not* the document. It only renders in a real browser. Two consequences: don't try to read a document by fetching this URL (use `get_*_details` instead), and don't treat a 200 as proof the link is valid — **the 404 for a wrong share code is also rendered client-side**, so status codes tell you nothing here.
>
> **There is currently no share URL an external agent can fetch without a browser.** The `api.systemhub.com` form is the machine-readable one — it returns the published document as JSON — but it currently 403s externally (see the known issue above). Until that's fixed, hand share links to *people*, and give programs MCP access instead.

`get_*_details` responses include a `shareLink` field (the URL, or `null` if none exists).

## Rules for agents

- **Never hide an existing share link.** When presenting a document's details, always surface its share link if one exists — it's part of the document's identity, not metadata to trim.
- **Say which kind of link you're giving.** "Here's the share link (public, no login)" vs "here's the app link (they'll need to log in)". The difference matters to the user even when it doesn't matter to you.
- **Treat share links as public.** Before generating one, make sure the user understands anyone with the URL can read the document. Don't generate share links for sensitive documents unprompted.

Next: **[Errors & limits →](/docs/concepts/errors-and-limits)**