Skip to main content
← All 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 →

Expiry, use limits and sessions limit different things

Expiry, use limits and sessions limit different things
ControlWhat it limitsWhat it leaves open
ExpiryWhen the link can be usedHow many times, and by how many people, before then
Use limitHow many times the link can be redeemedHow long the access it grants lasts
Session durationHow long access lasts after redemptionHow 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. 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
  5. 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.

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.

Building the gateway yourself: what each part must do
PartWhat it must doWith qURL
RedemptionCheck and mark the token in one atomic step, so two simultaneous requests cannot both redeem itThe first successful opening consumes the link
Every request afterIssue a short session and check it on every request, including Range requests that resume a downloadEach request is authorized at qURL’s edge for the life of the session
Downstream URLsNever hand the redeemer a reusable URL: it keeps its own rulesNothing to hand over: the file is served through the session
FailureA failed setup after redemption must not reset the tokenIf a visit fails after qURL consumes the link, send a fresh one with qurl share
RevocationRevoking a token ends the sessions it openedRevoke one link through the API with an account; qurl restart ends open sessions

Sources: API reference, Agent skill.

How each signed URL behaves

How each signed URL behaves
MechanismReuse before expiryLongest lifeRevoking one linkA download running at expiry
S3 presigned URLYes, by anyone holding it7 days (12 hours from the console), less with temporary credentialsNot per URL: revoke the signing credentials or tighten the bucket policyContinues: expiry is checked when a request starts
R2 presigned URLYes, by anyone holding it7 daysNot described in R2’s presigned URL documentationNot stated
Azure SASValid for the interval it allows7 days for a user delegation SAS; the expiry you set for the othersThrough a stored access policy, a key rotation or revoking user delegation keysNot stated
qURL link from qurl shareNo: it opens onceUp to 24 hours to open without an account, 30 days with one; then a session of up to 24 hoursRevoke one link through the API with an account; invitations one by oneCancelled at the session deadline

Sources: AWS presigned URLs, R2 presigned URLs, Azure SAS overview, API reference.

A redemption gateway’s states

A redemption gateway’s states
StateHow a link gets thereWhat a request sees
IssuedCreated with an expiry and a use limitRedeemable
RedeemedThe first valid redemption, recorded atomicallyA session for the redeemer; the link itself is spent
ExpiredThe expiry passed before redemptionRefused
RevokedThe issuer cancelled itRefused, and the sessions it opened can be ended

Sources: API reference.

Which control do you need?

Which control do you need?
If you needUse
Bounded access timeAn expiry on the link, plus a session limit
One admissionA single-use link, the default for qurl share
A named personAn email invitation with qurl access invite
A record of one completed copyA completion log in your file server, behind a single-use qURL link
Access you can take back per personPer-person grants: revoke one invitation, or one link through the API

Troubleshooting

Troubleshooting
If you seeDo this
The link was spent before the recipient downloaded anythingSomething 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 connectionsStart 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
More troubleshooting
If you seeDo 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: lineYour 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.

Or use the CLI →

Book a pilot

Tell us what to hide. We’ll scope a pilot.

Enterprise starts with a paid pilot on one application, typically 60 to 90 days, credited in full toward year one if you convert within 60 days. After that, an annual package sized to what you protect, not per seat.