# 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.

HTML version: https://tmphost.io/docs/pins/folder/ · All PIN strategies: https://tmphost.io/docs/pins.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`:

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

Result:

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

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

Result:

```json
{
  "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 https://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 https://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

- **Good for:** an agent sharing one folder with one person or group, who should not get into anything else.
- **Watch out:** every folder has a different PIN to pass on, and it can't be looked up later.
- **Instead:** one PIN for everything: https://tmphost.io/docs/pins/static.md. A code that stops working within 90 seconds: https://tmphost.io/docs/pins/authenticator.md