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 each person's Access QR 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 listed in the public_asset_folders server setting are visible (see Audience settings reference). The setting is empty by default, and both endpoints return 404 until it is set. 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=<access-link-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 token is the person's Access QR link. It stays valid until an operator selects Reset link or deletes the Personal code. The player and Editor generate the URL; an operator does not assemble it.

Person data endpoint

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

GET /api/person?t=<access-link-token>

Reset, malformed, forged, deleted-person, or otherwise invalid tokens return the same 401 response and no person data. A valid token returns the person's name, permitted details and files.

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 no longer valid');
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 a URL containing one, as a secret. It keeps working until the link is reset.
  • Use fictional data in documentation, support captures, and logs.