Nov 20, 20265 min read

Generate Google Cloud Storage Signed URLs in Python

Create V4 signed URLs for downloads and uploads with google-cloud-storage, sign on Cloud Run and GKE without a key file, cap upload size with a signed POST policy, and fix the errors that break signing.

Illustration for Generate Google Cloud Storage Signed URLs in Python

A signed URL gives a browser time-limited access to one Cloud Storage object without a Google account or a public bucket. The google-cloud-storage library signs it in one call with a key file, and fails on Cloud Run and GKE, where there is no key.

This guide covers download and upload URLs, keyless signing and upload size limits with version 3.x of the library.

GCS signed URLs in Python at a glance

GoalCallWatch out for
Download linkblob.generate_signed_url(version="v4", method="GET")Seven-day maximum
Upload with PUTmethod="PUT", content_type=...Client must send the same Content-Type
Upload with a size capclient.generate_signed_post_policy_v4(...)Multipart form, file field last
Sign on Cloud Run or GKEPass service_account_email and access_tokenNeeds Token Creator on the service account
Force a filenameresponse_disposition="attachment; filename=..."Quote the filename

How do you create a signed download URL?

With a service account key, such as in local development with GOOGLE_APPLICATION_CREDENTIALS set, the library signs with the private key and makes no network call. On Cloud Run, Cloud Functions and GKE the runtime credentials come from the metadata server and contain no key, so the helper below passes the service account email and a fresh access token, and the library calls the IAM Credentials signBlob API to sign:

from datetime import timedelta import google.auth from google.auth import compute_engine from google.auth.transport import requests as grequests from google.cloud import storage client = storage.Client() bucket = client.bucket("acme-exports") _credentials, _ = google.auth.default() def _signer() -> dict: if not isinstance(_credentials, compute_engine.Credentials): return {} # a service account key file signs locally # Metadata-server credentials have no private key: sign through IAM instead. if not _credentials.valid: _credentials.refresh(grequests.Request()) return { "service_account_email": _credentials.service_account_email, "access_token": _credentials.token, } def download_url(key: str, filename: str) -> str: return bucket.blob(key).generate_signed_url( version="v4", expiration=timedelta(minutes=15), method="GET", response_disposition=f'attachment; filename="{filename}"', **_signer(), ) def upload_url(key: str, content_type: str) -> str: return bucket.blob(key).generate_signed_url( version="v4", expiration=timedelta(minutes=10), method="PUT", content_type=content_type, # becomes part of the signature **_signer(), )

The service account the code runs as needs roles/iam.serviceAccountTokenCreator on itself for signBlob, which surprises people because it feels like granting a permission to the same identity twice. Without it, signing fails with a 403 that mentions iam.serviceAccounts.signBlob. The URL then works for anyone holding it, and the permission check at request time uses the signing service account, so it also needs roles/storage.objectViewer for downloads or roles/storage.objectCreator for uploads.

How do you let a browser upload?

The browser sends a PUT to the URL from upload_url with the same Content-Type that was signed, and any other value fails with SignatureDoesNotMatch. The bucket also needs a CORS configuration that allows your origin, the PUT method and the Content-Type header, set with gcloud storage buckets update gs://acme-exports --cors-file=cors.json.

A signed PUT cannot cap the file size. A V4 POST policy can, and the library generates one with conditions:

def avatar_upload_form(user_id: str) -> dict: policy = client.generate_signed_post_policy_v4( "acme-exports", f"avatars/{user_id}.png", expiration=timedelta(minutes=10), conditions=[["content-length-range", 1, 5 * 1024 * 1024]], fields={"content-type": "image/png"}, **_signer(), ) # The browser posts policy["fields"] plus a final "file" field to policy["url"]. return policy

What limits apply?

V4 signed URLs last at most seven days, and the library raises ValueError before signing anything longer. Each signature made through signBlob is an API call with its own quota, so a page that renders hundreds of thumbnails should sign once per object and cache the URL for part of its lifetime rather than signing on every render. The signed URL overview also notes that anyone with the URL can use it until it expires, so keep download lifetimes short for private documents.

How do you test signing locally?

Signing with a service account key works offline, so a unit test can build credentials from a throwaway key and assert on the generated URL's parameters. The keyless path cannot be emulated, which is why the helper returns an empty dict when a key file is in use: the same code runs on a laptop with a key and on Cloud Run without one, and the first deploy is where the Token Creator grant gets tested.

Signed URLs from a bucket declared in Python with Encore

Encore

Encore works alongside your Python framework, here FastAPI, as an SDK that declares infrastructure in code, and a bucket declared at module level has signed URL methods built in. Encore for Python is in private beta, and you can request an invite. The credential detection, Token Creator grant and signer plumbing above are not part of the app.

Application code passes through Encore and infrastructure guardrails to resources provisioned in your own AWS or GCP account.
Encore provisions the infrastructure your application needs in your own AWS or GCP account.
# exports/main.py import csv import io import encore from encore.storage import objects from fastapi import FastAPI # Cloud Storage on GCP, S3 on AWS, local storage under `encore run`. exports = objects.Bucket("exports", versioned=False) app = FastAPI() @app.post("/reports/{report_id}/export") async def export_report(report_id: str) -> dict: buf = io.StringIO() writer = csv.writer(buf) writer.writerow(["day", "orders"]) writer.writerow(["2026-11-19", 412]) key = f"{report_id}.csv" await exports.upload(key, buf.getvalue().encode(), content_type="text/csv") # Signed by Encore: no key file, signer or Token Creator grant in the code. return {"url": await exports.signed_download_url(key, ttl=900)} if __name__ == "__main__": encore.run(app)

encore run serves the bucket locally, so the endpoint returns a working link on a laptop. The service is registered with an encore.service.json file, and the SDK needs Python 3.9 or later. On deploy to your own GCP project, Encore creates the Cloud Storage bucket, as the GCP infrastructure docs describe, and Encore provisions an IAM role for the service, a service account on GCP. The same code creates an S3 bucket on AWS.

The bucket and its access come from the declaration, so a coding agent adding a second export type writes the endpoint and tests the link locally in the same change, and the signing permissions that usually fail on the first Cloud Run deploy are not something it has to get right.

Request a private-beta invite to try this setup:

Try Encore →

Frequently asked questions

How do I generate a signed URL for Google Cloud Storage in Python?

Get a blob with storage.Client().bucket(name).blob(key) and call blob.generate_signed_url(version="v4", expiration=timedelta(minutes=15), method="GET"). For uploads use method="PUT" and pass content_type, which the uploader must then send as its Content-Type header.

Why do I get "you need a private key to sign credentials"?

The credentials in use, such as the Cloud Run or GKE metadata server credentials, carry an access token but no private key. Refresh the default credentials and pass service_account_email and access_token to generate_signed_url, and the library signs through the IAM Credentials signBlob API instead of a local key.

What is the maximum expiration for a GCS signed URL?

Seven days (604,800 seconds) for V4 signed URLs. The Python library raises ValueError for anything longer, so generate links on demand instead of storing long-lived ones.

How do I limit the size of a signed upload?

Use client.generate_signed_post_policy_v4 with a ["content-length-range", min, max] condition, and the browser uploads with an HTML form POST that GCS rejects when the file is larger. A signed PUT URL cannot enforce a size limit. With Encore, a declared bucket's signed_upload_url creates upload URLs without any signing setup in the code. Encore for Python is in private beta (sign up at /py).

Deploy to your cloud on AWS and Google Cloud
without managing infrastructure

Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.

~/orders — claude
Claude Code
Claude Code v2.1.180Opus 5.5~/orders