# One-time download links: why expiration alone is not enough

> An expiring link is not a one-time link. How S3, R2 and Azure signed URLs behave, what one use can mean, and how qURL one-time links hand over a file.

Source: https://layerv.ai/guides/one-time-download-links/

---

[← All guides](https://layerv.ai/guides/) 

# One-time download links: why expiration alone is not enough

## Why qURL here

qURL™ links from qurl share are single-use by default, and the session they start ends on time, cancelling open transfers at the deadline. You get a redemption gateway with no token store to build, and the file is served from your machine.

[See how qURL compares to S3 presigned URLs →](https://layerv.ai/compare/qurl-vs-s3-presigned-urls/)

Copies a prompt for any agent that runs commands. 

## What you need

- A file on the machine where you run qurl
- The qURL CLI 3.4.1 or later
- Python 3, for the example file server

Content updated November 15, 2026.

## Expiry, use limits and sessions limit different things

__Expiry, use limits and sessions limit different things__
| Control          | What it limits                          | What it leaves open                                 |
| ---------------- | --------------------------------------- | --------------------------------------------------- |
| Expiry           | When the link can be used               | How many times, and by how many people, before then |
| Use limit        | How many times the link can be redeemed | How long the access it grants lasts                 |
| Session duration | How long access lasts after redemption  | How many requests, or files, that session fetches   |

## What “one use” means

Pick the event you are counting, because the choices differ: the first redemption of the link, the first HTTP request, an admitted session, or a completed transfer. A link that counts redemptions can admit one session that downloads ten files. A link that counts requests breaks the moment a browser asks for a second resource or resumes a download with a Range request.

A qURL link from `qurl share` counts redemptions: the first successful opening consumes it and starts one session for that browser. Inside that session the recipient can retry or resume a download, and a forwarded copy of the link is already dead. When --session-duration ends, new requests are refused and open transfers are cancelled.

Exchanging a one-time token for a downstream URL, such as a fresh presigned URL, does not make the downstream URL single-use: it keeps its own rules and stays reusable until it expires. One-time behaviour holds only where every protected request is checked. qURL authorizes each request at its edge for the life of the session.

## Steps

Expiry limits when a link works; a use limit limits how many times. S3 and R2 presigned URLs are reusable until they expire, and an Azure SAS works for its whole interval, so a one-time download needs a redemption step in front of the file. qURL links from `qurl share` do this by default: one opening, one session, then “Access link invalid”.

1. ### Install the qURL CLI  
On macOS, install it with Homebrew. On Linux and Windows, download the package for your platform from the latest release; the CLI page lists each one. Nothing asks you to sign up.  
```  
brew install layervai/tap/qurl
qurl --version
```
2. ### Serve the folder on this machine only  
Any static file server works. Binding it to 127.0.0.1 keeps it off your network, so qURL is the only way in. Leave it running in its own terminal.  
```  
python3 -m http.server 8000 --bind 127.0.0.1 --directory ./export
```
3. ### Publish it  
The first publish creates this device’s identity with no account and prints the resource’s CRID. The resource is private: nobody can open it until you share a link.

**For a one-time link:** Use the default private access policy.  
```  
qurl publish http://127.0.0.1:8000
```

**For an email invitation:** Use the invite-only access policy.  
```  
qurl publish http://127.0.0.1:8000 --access invite_only -o json
```
4. ### Make a single-use link  
If you published for a one-time link, use this command. --ttl is how long the link waits to be opened; --session-duration is how long the download window lasts once it is. The first opening consumes the link.  
```  
qurl share <CRID> --ttl 1h --session-duration 15m
```

**Check:** The expiry line under the link says “single use”.
5. ### Send the link to one person  
Send it in a direct message, not a public channel: whoever opens it first uses it. Avoid email and apps that preview links, because a scanner that runs the page could use its one opening. Don’t open it yourself to check it, for the same reason. Run `qurl share` again whenever you need a fresh link.
6. ### For a named recipient, invite them instead  
If you published for an email invitation, skip the one-time link and invite the recipient by email. Only that address gets in, after verifying the mailbox and saving a passkey, and you can revoke that one person at any time.  
```  
qurl access invite <CRID> --email recipient@example.com -o json
```
7. ### Close the handoff  
An unopened link ends at its --ttl and an opened session at its --session-duration. `qurl stop` stops serving the folder until `qurl start`; `qurl delete` retires the resource for good after asking you to confirm.  
```  
qurl stop <CRID>     # pause; qurl start <CRID> resumes
qurl delete <CRID>   # permanent; asks you to confirm
```

## What the recipient sees

The recipient opens the link in a browser, sees the folder and downloads the file during the session.

Opening the same link again shows “Access link invalid”.

## Building the gateway yourself: what each part must do

Every row is code you write, test and keep running. qURL ships each one as the default.

__Building the gateway yourself: what each part must do__
| Part                | What it must do                                                                                      | With qURL                                                                        |
| ------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| Redemption          | Check and mark the token in one atomic step, so two simultaneous requests cannot both redeem it      | The first successful opening consumes the link                                   |
| Every request after | Issue a short session and check it on every request, including Range requests that resume a download | Each request is authorized at qURL’s edge for the life of the session            |
| Downstream URLs     | Never hand the redeemer a reusable URL: it keeps its own rules                                       | Nothing to hand over: the file is served through the session                     |
| Failure             | A failed setup after redemption must not reset the token                                             | If a visit fails after qURL consumes the link, send a fresh one with qurl share  |
| Revocation          | Revoking a token ends the sessions it opened                                                         | Revoke one link through the API with an account; qurl restart ends open sessions |

Sources: [API reference](https://layerv.ai/docs/qurls.md) , [Agent skill](https://layerv.ai/skills/qurl/SKILL.md).

## How each signed URL behaves

__How each signed URL behaves__
| Mechanism                 | Reuse before expiry              | Longest life                                                                                  | Revoking one link                                                               | A download running at expiry                       |
| ------------------------- | -------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------- |
| S3 presigned URL          | Yes, by anyone holding it        | 7 days (12 hours from the console), less with temporary credentials                           | Not per URL: revoke the signing credentials or tighten the bucket policy        | Continues: expiry is checked when a request starts |
| R2 presigned URL          | Yes, by anyone holding it        | 7 days                                                                                        | Not described in R2’s presigned URL documentation                               | Not stated                                         |
| Azure SAS                 | Valid for the interval it allows | 7 days for a user delegation SAS; the expiry you set for the others                           | Through a stored access policy, a key rotation or revoking user delegation keys | Not stated                                         |
| qURL link from qurl share | No: it opens once                | Up to 24 hours to open without an account, 30 days with one; then a session of up to 24 hours | Revoke one link through the API with an account; invitations one by one         | Cancelled at the session deadline                  |

Sources: [AWS presigned URLs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html) , [R2 presigned URLs](https://developers.cloudflare.com/r2/api/s3/presigned-urls/) , [Azure SAS overview](https://learn.microsoft.com/en-us/azure/storage/common/storage-sas-overview) , [API reference](https://layerv.ai/docs/qurls.md).

## A redemption gateway’s states

__A redemption gateway’s states__
| State    | How a link gets there                           | What a request sees                                  |
| -------- | ----------------------------------------------- | ---------------------------------------------------- |
| Issued   | Created with an expiry and a use limit          | Redeemable                                           |
| Redeemed | The first valid redemption, recorded atomically | A session for the redeemer; the link itself is spent |
| Expired  | The expiry passed before redemption             | Refused                                              |
| Revoked  | The issuer cancelled it                         | Refused, and the sessions it opened can be ended     |

Sources: [API reference](https://layerv.ai/docs/qurls.md).

## Which control do you need?

__Which control do you need?__
| If you need                         | Use                                                                   |
| ----------------------------------- | --------------------------------------------------------------------- |
| Bounded access time                 | An expiry on the link, plus a session limit                           |
| One admission                       | A single-use link, the default for qurl share                         |
| A named person                      | An email invitation with qurl access invite                           |
| A record of one completed copy      | A completion log in your file server, behind a single-use qURL link   |
| Access you can take back per person | Per-person grants: revoke one invitation, or one link through the API |

## Troubleshooting

__Troubleshooting__
| If you see                                                       | Do this                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The link was spent before the recipient downloaded anything      | Something opened it first, or it passed its --ttl. Run qurl share again and send the new link in a direct message. [Fix a one-time link that was already used →](https://layerv.ai/guides/one-time-link-already-used/)                                                                                                                                                                                                                |
| qurl publish says the local app is not accepting TCP connections | Start the app first and check that curl works on the same address. qurl publish connects to localhost as 127.0.0.1, so if your app listens only on IPv6 (on macOS or Linux, lsof -iTCP -sTCP:LISTEN -nP shows \[::1\]), publish 'http://\[::1\]:PORT' instead, or start the dev server with --host 127.0.0.1 and publish that address. Neither requires listening on your LAN. Keep the quotes: zsh treats the brackets as a pattern. |

__More troubleshooting__
| If you see                                                                                                             | Do this                                                                                                                                                                                                                                                                                                                       |
| ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The recipient sees “Access link invalid”                                                                               | The link was already used or has expired. Run qurl share again and send the new link.                                                                                                                                                                                                                                         |
| The recipient sees “Resource not found”                                                                                | The resource was deleted after the link was made. Publish the app again, then run qurl share and send the new link.                                                                                                                                                                                                           |
| publish rejects http://127.0.0.1 with “only HTTPS URLs are allowed”, asks you to log in, or prints no Access: line     | Your qURL CLI is out of date. On macOS run brew update, then brew upgrade qurl; elsewhere install the latest release. After updating, qurl --version prints 3.4.1 or later, and every publish is private by default.                                                                                                          |
| publish says this Linux session “can’t reach a systemd user manager”                                                   | You are in a container or sandbox without a user service manager. Run qurl publish with --foreground; sharing lasts as long as that process runs. [Container and CI setup →](https://layerv.ai/guides/share-from-a-container-or-ci/)                                                                                          |
| publish says “Quota Exceeded” with “protected resource limit reached”, or “Your qURL account has reached a plan limit” | You can see this without an account: a device with no account can keep up to 3 active resources, with links that last up to 24 hours. Run qurl list --status active, then qurl delete <CRID> for any you no longer need (it asks you to confirm; --yes skips that). qurl stop keeps the resource, so it does not free a slot. |

## Frequently Asked Questions

Is an S3 presigned URL single-use? 

No. AWS says a presigned URL can be used multiple times until it expires, and calls it a bearer token. R2 presigned URLs are reusable until they expire as well.

What does a qURL single-use link count? 

One opening. The first browser to open it gets one session, and that session can retry or resume the download until it ends, while a forwarded copy of the link shows “Access link invalid”. If your app also needs a record of a completed copy, log it on the server.

Can a link preview use up a one-time link? 

A plain link preview cannot: the secret part of the link comes after the #, and browsers and HTTP clients never send that part to a server, so a preview bot that fetches the link gets only the opening page. A scanner that opens the link in a real browser and runs its scripts can use the one opening, and the reviewer then sees “Access link invalid”. Send the link in a direct message to the reviewer, never open it yourself, and if it was used up, run qurl share again: the app does not need to be published again.

Who else can reach my app while the link is open? 

Opening the link starts a session for that browser, which lasts 1 hour by default. After a browser opens it, another browser on the same public IP cannot use its access. A script or agent that opens the link without a browser is admitted by its network address instead, which other devices on that public IP share until the session ends. A link admits whoever opens it: the API’s IP and country rules do not apply to the signed links qurl share issues. Keep your app’s own sign-in for anything sensitive.

## Related Resources

[qURL vs S3 presigned URLs →](https://layerv.ai/compare/qurl-vs-s3-presigned-urls/) [qURL vs Cloudflare R2 presigned URLs →](https://layerv.ai/compare/qurl-vs-cloudflare-r2/) [qURL vs Azure Blob SAS →](https://layerv.ai/compare/qurl-vs-azure-blob-sas/) [Guide: One-time link already used or expired →](https://layerv.ai/guides/one-time-link-already-used/) [Guide: Make a one-time link for a demo →](https://layerv.ai/guides/one-time-link-for-a-demo/) [Guide: Revoke access to a shared app →](https://layerv.ai/guides/revoke-access-to-a-shared-app/) [Glossary: Single-use link →](https://layerv.ai/glossary/single-use-link/)

## Hand over a file now

Serve the folder on 127.0.0.1, publish it, and send one person a link that opens once. No account, no upload.

[Or use the CLI →](https://layerv.ai/cli/)



---

*This markdown version is auto-generated from [https://layerv.ai/guides/one-time-download-links/](https://layerv.ai/guides/one-time-download-links/) for AI agents. Curated agent resources: [llms.txt](https://layerv.ai/llms.txt). For the full interactive experience, visit the HTML version.*

