# Presigned URLs (/tools/s3-gateway/presigned-urls)
A presigned URL lets someone download an object without Shelby credentials. Your server signs
the URL with your access key ID and secret, then hands it out. Until the URL expires, anyone
who has it can read that one object, from a browser, `curl` or any HTTP client.
On Shelby, presigned URLs are for downloads:
* **GET and HEAD only.** You can't presign an upload, a delete or a listing. Do those from
your server with your credentials.
* **One object per URL.** To share everything under a prefix, [share a folder](#share-a-folder).
* **Up to 7 days.** Set the expiry anywhere from 1 second to 604,800 seconds (7 days).
* **Signed with region `default` and path-style addressing.** The client setup in each
[quickstart](/tools/s3-gateway/quickstarts/aws-cli) already uses both.
## Create a download link
```bash
aws s3 presign "s3://$SHELBY_BUCKET/reports/q3.pdf" --expires-in 3600 --profile shelby
```
The `shelby` profile comes from the [AWS CLI quickstart](/tools/s3-gateway/quickstarts/aws-cli).
`aws s3 presign` only makes download (GET) links, and can't set the response overrides below.
```python
from shelby_s3 import bucket, s3
url = s3.generate_presigned_url(
"get_object",
Params={"Bucket": bucket, "Key": "reports/q3.pdf"},
ExpiresIn=3600,
)
```
`shelby_s3.py` is the client from the [Python quickstart](/tools/s3-gateway/quickstarts/python).
Keep its `region_name="default"`: a link signed for any other region is refused.
```bash
npm install @aws-sdk/s3-request-presigner
```
```ts
import { GetObjectCommand } from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
import { Bucket, s3 } from "./shelby-s3.ts";
const url = await getSignedUrl(
s3,
new GetObjectCommand({ Bucket, Key: "reports/q3.pdf" }),
{ expiresIn: 3600 },
);
```
`shelby-s3.ts` is the client from the
[JavaScript quickstart](/tools/s3-gateway/quickstarts/javascript). Its `region: "default"` and
`forcePathStyle: true` are both part of the signature. Keep its
`responseChecksumValidation: "WHEN_REQUIRED"` too: without it, the SDK adds
`x-amz-checksum-mode` to the link, and Shelby refuses the link with `501 NotImplemented`.
Each example signs a link that works for an hour (3,600 seconds). The recipient needs no
credentials and no S3 client: `curl "$url"` works, and so does opening the link in a browser.
In an app, sign the link on your server when a signed-in user asks for it, after checking that
they may read the object, and return it to them.
Pass the URL on exactly as it was signed. The endpoint, method, path, expiry and every query
parameter are part of the signature, so changing any of them breaks the link.
## Set the filename or type
A GET link can override some headers of the response, without changing the stored object. The
most useful is `Content-Disposition`: `attachment` makes a browser save the file under the
name you choose, instead of showing it.
```python
url = s3.generate_presigned_url(
"get_object",
Params={
"Bucket": bucket,
"Key": "reports/q3.pdf",
"ResponseContentDisposition": 'attachment; filename="q3-report.pdf"',
},
ExpiresIn=3600,
)
```
```ts
const url = await getSignedUrl(
s3,
new GetObjectCommand({
Bucket,
Key: "reports/q3.pdf",
ResponseContentDisposition: 'attachment; filename="q3-report.pdf"',
}),
{ expiresIn: 3600 },
);
```
| Query parameter | SDK parameter | Overrides |
| ------------------------------ | ---------------------------- | --------------------- |
| `response-content-disposition` | `ResponseContentDisposition` | `Content-Disposition` |
| `response-content-type` | `ResponseContentType` | `Content-Type` |
| `response-content-language` | `ResponseContentLanguage` | `Content-Language` |
| `response-content-encoding` | `ResponseContentEncoding` | `Content-Encoding` |
`response-cache-control` and `response-expires` are refused with `400`, because Shelby sets
caching headers on presigned responses itself. See [Keep links safe](#keep-links-safe).
## Check an object without downloading it
A HEAD link returns the object's size, type and ETag without its body. Presign `head_object`
or `HeadObjectCommand`, then send a HEAD request with the link, for example with
`curl -I "$url"`. The method is part of the signature, so a HEAD link only works for HEAD, and
a GET link only for GET.
```python
url = s3.generate_presigned_url(
"head_object",
Params={"Bucket": bucket, "Key": "reports/q3.pdf"},
ExpiresIn=300,
)
```
```ts
import { HeadObjectCommand } from "@aws-sdk/client-s3";
const url = await getSignedUrl(
s3,
new HeadObjectCommand({ Bucket, Key: "reports/q3.pdf" }),
{ expiresIn: 300 },
);
```
HEAD requests don't count toward your organization's
[concurrent downloads](/tools/s3-gateway/limits#concurrent-downloads).
## Share a folder
A folder share gives someone read access to everything under a prefix, through one link. It's
a Shelby extension, not an S3 operation: you presign a GET of Shelby's `/_auth/folder` path,
with the bucket and prefix as query parameters, using the same access key ID and secret.
`generate_presigned_url` and `getSignedUrl` only sign S3 operations, so these examples sign the
request directly:
```python title="folder_share.py"
import os
from urllib.parse import quote, urlencode
from botocore.auth import S3SigV4QueryAuth
from botocore.awsrequest import AWSRequest
from botocore.credentials import Credentials
from shelby_s3 import bucket, s3
def folder_share_url(prefix: str, expires: int = 600) -> str:
"""Sign a link that lets whoever opens it read everything under prefix."""
query = urlencode({"bucket": bucket, "prefix": prefix}, quote_via=quote)
request = AWSRequest(
method="GET", url=f"{s3.meta.endpoint_url}/_auth/folder?{query}"
)
credentials = Credentials(
os.environ["SHELBY_ACCESS_KEY_ID"], os.environ["SHELBY_SECRET_ACCESS_KEY"]
)
S3SigV4QueryAuth(credentials, "s3", s3.meta.region_name, expires=expires).add_auth(
request
)
return request.url
share_url = folder_share_url("contracts/customer-123/")
```
`folder_share_url` takes the endpoint, region and bucket from `shelby_s3.py`, the client from
the [Python quickstart](/tools/s3-gateway/quickstarts/python). botocore comes with boto3, so
there's nothing else to install.
```bash
npm install @aws-sdk/s3-request-presigner @aws-sdk/util-format-url
```
```ts title="folder-share.ts"
import type { S3Client } from "@aws-sdk/client-s3";
import { S3RequestPresigner } from "@aws-sdk/s3-request-presigner";
import { formatUrl } from "@aws-sdk/util-format-url";
/** Sign a link that lets whoever opens it read everything under Prefix. */
export async function getSignedFolderUrl(
s3: S3Client,
{ Bucket, Prefix }: { Bucket: string; Prefix: string },
{ expiresIn = 600 }: { expiresIn?: number } = {},
): Promise {
if (Prefix === "") throw new Error("Prefix must not be empty");
const endpoint = await s3.config.endpoint?.();
if (endpoint?.protocol !== "https:") {
throw new Error("Folder shares need an HTTPS endpoint");
}
const presigner = new S3RequestPresigner({ ...s3.config });
const signed = await presigner.presign(
{
method: "GET",
protocol: endpoint.protocol,
hostname: endpoint.hostname,
port: endpoint.port,
path: `${endpoint.path.replace(/\/+$/, "")}/_auth/folder`,
query: { bucket: Bucket, prefix: Prefix },
headers: {},
},
{ expiresIn },
);
return formatUrl(signed);
}
```
```ts
import { getSignedFolderUrl } from "./folder-share.ts";
import { Bucket, s3 } from "./shelby-s3.ts";
const shareUrl = await getSignedFolderUrl(s3, {
Bucket,
Prefix: "contracts/customer-123/",
});
```
`getSignedFolderUrl` signs with the client from `shelby-s3.ts`, so it uses the same endpoint,
region and credentials as the rest of your code.
Both examples sign a link that's valid for 10 minutes. As with object links, the most is 7
days. The prefix can't be empty, so a folder share can't cover a whole bucket. If it doesn't
end in `/`, Shelby adds one: `contracts/customer-123` shares `contracts/customer-123/`, not
`contracts/customer-1234/`.
### What the recipient does
1. They open the link in a browser as a normal link: clicked, or pasted into the address bar.
2. Shelby checks the signature, sets a cookie for `s3.beta.shelby.xyz`, and redirects to a
listing of the prefix. The listing is S3's `ListObjectsV2` XML, not a file browser.
3. In the same browser, they open any object under the prefix by its plain URL,
`https://s3.beta.shelby.xyz//`. The URL has no signature and no query string:
the cookie grants access. Each `` in the listing is an object's full key.
### What the cookie allows
| Request | Result |
| ---------------------------------------------------- | ---------------------------------------------------------- |
| List the prefix, or a narrower prefix | Allowed |
| GET or HEAD an object under the prefix | Allowed |
| An object outside the prefix | `403` "Folder cookie does not grant access to this object" |
| A listing outside the prefix, or of the whole bucket | `403` "Folder cookie cannot list outside its prefix" |
| An upload, delete or any other write | `403` "Folder cookies allow only read operations" |
* **Access ends when the link expires.** The cookie lasts until the link's own expiry, not for
a fresh period from when it's opened. A 10-minute link opened after 8 minutes gives 2 minutes
of access.
* **A browser holds one folder share at a time.** Opening a second share link replaces the
first.
* **The cookie only goes with direct visits.** It's `SameSite=Lax`, so the browser sends it
when the recipient opens a Shelby URL themselves, from the listing, a link or the address
bar. It doesn't send it with `fetch` from another site, or for an `` or `