Clarity deep links — supported destinations and boundaries

Public contract

Supported entry points.

The list describes only routes that are defensible as external navigation. Internal tab, help, support, staff, marketplace and invitation routes do not automatically become a stable partner API.

clarity://assistant

Open Ariadne

Opens the existing Assistant tab. The link passes neither a prompt nor account data.

Supported

clarity://assistant/voice

Start voice input

Opens Ariadne and triggers the existing voice start in the app router. The permission decision stays in the app.

Supported

clarity://voice-notes

Open Voice Notes

Opens the existing Voice Notes interface. No recording is transferred through the URL.

Supported

clarity://session/{catalogue-id}

Open Guided Session

Opens only an ID known to the app catalogue. Unknown IDs are not resolved fuzzily.

Allowlist

https://{entitled-domain}/clarity/session/{catalogue-id}

Session web fallback

The noindex fallback accepts only the public ID allowlist and loads no account, progress or session data.

Release-bound

Resolution

Validate, then open.

The app separates custom-scheme routes from HTTP(S). Guided Session IDs are checked against the existing catalogue. Before a new session appears, existing root-owned presentation state is reset; an unknown ID opens nothing.

route-resolution.txt

1  recognise scheme or HTTPS
2  validate host and path shape
3  check catalogue-id against the released catalogue
4  close competing presentation
5  open the exact requested session

unknown host → ignore
unknown catalogue-id → no route

No user data in the URL

The route carries navigation. Account, prompt, progress, session content, permission and entitlement are not embedded in a query or path.

Universal Links

Three parts, one release.

App router: The current iOS router knows /clarity/session/{catalogue-id} only on explicitly supported hosts.
AASA: The website serves the association file at /apple-app-site-association and /.well-known/apple-app-site-association as JSON without a redirect.
Signed entitlement: The domain must be included as an Associated Domain in the shipped app build. A website or build variable alone does not activate a Universal Link.
Web fallback: If the app does not take over, the web route shows only the allowlist-validated session handoff and a safe download route.

Public app ID, not a credential

RR24DD5K64.com.moritzzinecker.clarity is the Team/Bundle combination currently listed in AASA. It must be checked against the actually signed release build before production.

Security boundaries

What a link must not do.

No foreign HTTP(S) host may open a Clarity context.
A free or newly configured domain is not automatically part of the app entitlement.
The fallback accepts no arbitrary session ID and does not turn it into a network or database search.
The link transfers no sign-in, role, permission or plan entitlement.
Internal support and staff routes are not a documented partner path and remain bound to app status, UUID and role.
New HTTPS paths are documented publicly only when the app router, AASA, fallback and release build express the same contract.

Release check

Before every new domain or route.

1 · Router: The signed app recognises exactly the documented host, path and fallback.
2 · Catalogue: Every public session ID exists explicitly in both the web allowlist and app catalogue.
3 · AASA: Both standard paths respond directly with correct JSON and no redirect.
4 · Entitlement: The shipped build contains the intended Associated Domain.
5 · Negative tests: Foreign host, unknown ID, missing app and missing permission fail safely.