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”.
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 --versionServe 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 ./exportPublish 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:8000For an email invitation: Use the invite-only access policy.
qurl publish http://127.0.0.1:8000 --access invite_only -o jsonMake 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 15mCheck: The expiry line under the link says “single use”.
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 shareagain whenever you need a fresh link.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 jsonClose the handoff
An unopened link ends at its --ttl and an opened session at its --session-duration.
qurl stopstops serving the folder untilqurl start;qurl deleteretires 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.
More
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.
| 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, Agent skill.
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, R2 presigned URLs, Azure SAS overview, API reference.
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.
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
| 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 → |
| 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. |
Show 5 more fixes
| 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 → |
| 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.
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.