SveltyCMS supports time-limited, optionally password-protected share links for private media assets. Links are created by authenticated users and consumed via a public token gate.

---

Endpoints Overview

Operation	Endpoint	Method	Auth
Create link	/api/media/share/{mediaId}	POST	media:write
Access / download	/api/media/share?id=&token=	GET	Public (valid token)
Revoke link	/api/media/share/{mediaId}/{token}	DELETE	media:write
Extend expiry	/api/media/share/{mediaId}/{token}	PATCH	media:write

Implementation: handleMediaShareCreate, handleMediaShareDownload, handleMediaShareRevoke, and handleMediaShareExtend in src/routes/api/[...path]/handlers/media.ts. Token logic lives in src/utils/media/sharing.ts.

---

Create Share Link

Endpoint: POST /api/media/share/{mediaId}

Payload:

{
  "expiryHours": 24,
  "password": "optional-secret"
}

• expiryHours — null or omitted for non-expiring links (admin UI offers 1h, 24h, 7d, or never).
• password — optional; stored as SHA-256 hash on the link record.

Response:

{
  "success": true,
  "data": {
    "token": "…",
    "expiresAt": "2026-07-11T12:00:00.000Z"
  }
}

Admin UI: The Share tab in media-details-modal.svelte calls this endpoint, then reloads the asset to display the new link in the active shares list.

---

Access Shared Asset

Endpoint: GET /api/media/share

Purpose: Validates access permissions (token existence, expiry, password) and delivers the file or an appropriate error status.

Parameters (Query Only)

Parameter	Type	Required	Description
id	String	Yes	The unique internal ID of the media asset within SveltyCMS.
token	String	Yes	The cryptographically secure sharing token provided by the owner.
password	String	Conditional	Required when the link has password protection enabled.

Request Flow & Security Model

The server processes a multi-stage validation pipeline before streaming any content:

1. Existence Check: Verify both id and token.
2. Token Validation: Look up the shared link record associated with token. If not found or expired, access is denied immediately (404 or 410).
3. Password Gate (If Active): If a password hash is stored on the link, the provided password must match. Failure returns 401.

Success Responses

Status 200 OK (metadata preview) — JSON wrapper with filename, mimeType, size, and download URL.

{
  "success": true,
  "data": {
    "filename": "example-asset.pdf",
    "mimeType": "application/pdf",
    "size": 102400,
    "url": "/api/media/share?id=…&token=…"
  }
}

Status 200 OK (direct download) — When validation passes, the server may stream binary data directly with appropriate Content-Type and Content-Disposition headers.

Error Responses

HTTP Status	Description
400 Bad Request	Missing required parameters (id, token) or incorrect format.
401 Unauthorized	Incorrect password for a password-protected link.
404 Not Found	No asset found matching id, or no share link found for the given token.
410 Gone	The shared link was valid but its designated expiry date has passed.

---

Revoke Share Link

Endpoint: DELETE /api/media/share/{mediaId}/{token}

Immediately deactivates the token. The link record is removed from metadata.sharedLinks on the media item.

Admin UI: Each active link in the Share tab of media-details-modal.svelte exposes a revoke action that calls this endpoint.

---

Extend Share Link

Endpoint: PATCH /api/media/share/{mediaId}/{token}

Payload: { "expiryHours": 168 } — pushes the expiry forward from the current time.

---

Technical Notes

• Tenant isolation: All share lookups are scoped by tenantId on the media record to prevent cross-tenant token reuse.
• Published-reference gate: Share link creation does not mutate file bytes; version/delete/manipulate operations on shared assets remain subject to the published-reference protection.
• Virtual folder moves: POST /api/media/move only updates logical folderId. Storage paths and share tokens remain valid — reorganizing assets in the gallery does not revoke or break active share links.
• Related DAM UI: Bulk download, storage analytics, version compare, and virtual-folder drag-and-drop are documented in Media Reference and Media System Architecture.

---

Related

• Media Reference (media.ts) — including POST /api/media/move
• Media System Architecture
• API Reference