Folder PIN

One folder gets a random 6 digit PIN of its own, made when the agent asks and shown only in that answer. It works while the account PIN is off.

LLM-friendly version (Markdown): https://tmphost.io/docs/pins/folder.md

Why a folder PIN

An account PIN is one secret for everything. A folder PIN is scoped to one folder: the person who gets a report's link and PIN can open that report and nothing else, and a PIN that leaks unlocks one folder that expires soon anyway. The agent makes it in the same call that creates the folder, so protecting a share takes no setup from the owner.

tmphost.io picks the PIN from a cryptographic random source and keeps only its bcrypt hash. Neither the agent nor the owner can read it back later, so a database leak does not reveal it either.

CLI

Add --pin when the upload creates a new folder, or give an existing folder a PIN with tmphost file pin:

$ tmphost file upload report.pdf --pin
Uploading 1 files (cost: 3 credits)
https://k7q2m9xa.file.tmphost.io/report.pdf

id:      k7q2m9xa
url:     https://k7q2m9xa.file.tmphost.io/
expires: 2026-10-24 04:15 UTC (in 30m)
pin:     482913 (shown only once; or open https://k7q2m9xa.file.tmphost.io/?pin=482913)
$ tmphost file pin --id k7q2m9xa
id:      k7q2m9xa
url:     https://k7q2m9xa.file.tmphost.io/
pin:     590274 (shown only once; or open https://k7q2m9xa.file.tmphost.io/?pin=590274)

--pin can't be combined with --id: a folder gets its PIN when it is created, or later with tmphost file pin. With --json the PIN is in pin, next to "pinMode":"folder". PINs and ids here are examples.

MCP

Pass pin: true on the upload that creates the folder (no id), or call the pin action with the folder's id:

{
  "action": "upload",
  "fileName": "index.html",
  "format": "textContent",
  "textContent": "<h1>Report</h1>",
  "pin": true
}

{
  "id": "k7q2m9xa",
  "url": "https://k7q2m9xa.file.tmphost.io/index.html",
  "expiresAt": "2026-10-24T04:15:00Z",
  "pinMode": "folder",
  "pin": "482913",
  ...
}

{ "action": "pin", "id": "k7q2m9xa" }

{
  "id": "k7q2m9xa",
  "url": "https://k7q2m9xa.file.tmphost.io/",
  "expiresAt": "2026-10-24T04:15:00Z",
  "pinMode": "folder",
  "pin": "590274"
}

pin: true together with an id is refused: use the pin action for a folder that already exists.

HTTP API

$ curl -sS -X POST -H "Authorization: Bearer $TOKEN" -d '{"pin":true}' $API/folders
{"folder":{"id":"k7q2m9xa",...,"pinMode":"folder","pin":"482913"}}
$ curl -sS -X POST -H "Authorization: Bearer $TOKEN" $API/folders/k7q2m9xa/pin
{"folder":{"id":"k7q2m9xa",...,"pinMode":"folder","pin":"590274"}}
$ curl -sS -X DELETE -H "Authorization: Bearer $TOKEN" $API/folders/k7q2m9xa/pin
{"folder":{"id":"k7q2m9xa",...}}

POST /folders/{id}/pin answers 201 with Cache-Control: no-store. DELETE removes the PIN, and the folder opens for anyone with the link again. Later reads of the folder carry pinMode but never pin.

Web app

On the Files page of app.tmphost.io, each folder shows whether a PIN guards it and can get a new PIN or lose its PIN. A new PIN is shown once, with buttons to copy the PIN or a link that opens the folder without asking.

A PIN for every agent folder

The owner can have tmphost.io do this for every folder an agent creates: on app.tmphost.io/security, under Agent folders, tick Give each folder an agent creates a PIN of its own ("agentPins":true in PUT /users/me/pin). Each new folder from the MCP server, the CLI or the API then comes back with its own pin, without the agent asking. Folders uploaded on the web app's own Upload page are left alone. The setting only applies while the account PIN is off.

Rules

• Shown once. pin is only in the answer that made it. Hand it to the user right away; if it is lost, make a new one.
• A new PIN replaces the old one. The old PIN stops working, and so does every browser cookie made with it.
• Account PIN first. While a static or authenticator PIN is on, asking for a folder PIN answers 409 ("the account pin guards this folder"), and "pin":true on a new folder is ignored. Folder PINs set before stay stored and guard their folders again once the account PIN is off.
• Hand it over apart from the link. Give the user the PIN on its own line, so they can send it by another route than the URL. A ?pin= link is handy, but it is the URL and the PIN in one piece.

When to pick it