Skip to content

Developer reference: public assets and Personal Folder data

Most operators should use the built-in Personal Folder Access QR workflow. It creates and delivers short-lived access automatically; visitors must never be asked to mint tokens, call APIs, or copy credentials.

The endpoints below are for approved custom Hosted Sites and integration developers.

Public assets

GET /api/public/assets?dir=<approved-folder>
GET /api/public/assets/<approved-folder>/<path>

Only asset folders approved by the administrator are visible. Private folders, unpublished assets, path traversal, alternate separators, and symlink escapes are rejected. Do not expose the whole asset root as a shortcut.

Personal Folder page

The normal QR destination is:

/person-access?t=<short-lived-person-token>

This Showcase-owned page reads the person's permitted details and owned-item tree, supports allowed detail edits, and presents preview/download links. The player and Editor generate the URL; an operator does not assemble it.

Person data endpoint

An approved custom site can receive the same short-lived token in its launch URL and call:

GET /api/person?t=<short-lived-person-token>

Expired, malformed, forged, deleted-person, or mismatched tokens return the same 401 response and no person data.

const token = new URLSearchParams(location.search).get('t');
const response = await fetch(`/api/person?t=${encodeURIComponent(token ?? '')}`);
if (!response.ok) throw new Error('This Personal Folder link is invalid or expired');
const person = await response.json();

A server-side mint endpoint exists for authorized product flows, but it is not an operator or visitor workflow. Custom systems should use connector credentials and their approved integration endpoints instead of extracting editor access tokens.

Privacy rules

  • Expose only fields needed by the experience.
  • Never return login data, admin metadata, connector credentials, private notes, or another person's files.
  • Treat a person token or URL containing one as a temporary secret.
  • Use fictional data in documentation, support captures, and logs.