Signed URLs

This page provides an overview of signed URLs, which you use to give time-limited resource access to anyone in possession of the URL, regardless of whether they have a Google account. To learn how to create a signed URL, see V4 Signing Process with Cloud Storage Tools and V4 Signing Process with Your Own Program. To learn about other ways of controlling access to buckets and objects, see Overview of Access Control.


A signed URL is a URL that provides limited permission and time to make a request. Signed URLs contain authentication information in their query string, allowing users without credentials to perform specific actions on a resource. When you generate a signed URL, you specify a user or service account which must have sufficient permission to make the request that the signed URL will make. After you generate a signed URL, anyone who possesses it can use the signed URL to perform specified actions, such as reading an object, within a specified period of time.

When should you use a signed URL?

In some scenarios, you might not want to require your users to have a Google account in order to access Cloud Storage, but you still want to control access using your application-specific logic. The typical way to address this use case is to provide a signed URL to a user, which gives the user read, write, or delete access to that resource for a limited time. You specify an expiration time when you create the signed URL. Anyone who knows the URL can access the resource until the expiration time for the URL is reached or the key used to sign the URL is rotated.

Options for generating a signed URL

Cloud Storage supports several methods for generating a signed URL:

  • V4 signing with service account authentication: This signing mechanism is described below.

  • V2 signing with service account authentication: For more information about this signing mechanism, go here.

  • Signing with HMAC authentication: If you're an Amazon Simple Storage Service (Amazon S3) user, you can use your existing workflows to generate signed URLs for Cloud Storage. Simply specify Cloud Storage resources, point to the host, and use Google HMAC credentials in the process of generating the signed URL.

Signed URL example

The following is an example of a signed URL that was created following the V4 signing process with service account authentication:

This signed URL provided access to read the object cat.jpeg in the bucket example-bucket. The query parameters that make this a signed URL are:

  • X-Goog-Algorithm: The algorithm used to sign the URL.

  • X-Goog-Credential: Information about the credentials used to create the signed URL.

  • X-Goog-Date: The date and time the signed URL became usable, in the ISO 8601 basic format YYYYMMDD'T'HHMMSS'Z'.

  • X-Goog-Expires: The length of time the signed URL remained valid, measured in seconds from the value in X-Goog-Date. In this example the Signed URL expires in 15 minutes. The longest expiration value is 604800 seconds (7 days).

  • X-Goog-SignedHeaders: Headers that had to be included as part of any request that used the signed URL.

  • X-Goog-Signature: The authentication string that allowed requests using this signed URL to access cat.jpeg.

Using signed URLs with resumable uploads

When using signed URLs with resumable uploads to upload objects to your bucket, you only need to use the signed URL in the URI of the initial POST request. No data is uploaded in the POST request; instead, the request returns a session URI which is used in subsequent PUT requests to upload data. Since the session URI is, in effect, an authentication token, the PUT requests do not need to use the original signed URL. This behavior allows the POST request to be made by the server, avoiding the need for clients to have to deal with signed URLs themselves.

Resumable uploads are pinned in the region they start in. For example, if you create a resumable upload URL in the US and give it to a client in Asia, the upload still goes through the US. Performing a resumable upload in a region where it wasn't initiated can cause slow uploads. To avoid this, have the initial POST request constructed and signed by the server, but then give the signed URL to the client so that the upload is initiated from their location. Once initiated, the client can use the resulting session URI normally to make PUT requests that do not need to be signed.

Signed URL considerations

When working with signed URLs, keep in mind the following:

  • Signed URLs can generally be made for any XML API request; however, the Node.js Cloud Storage Client Libraries currently can only make signed URLs for individual objects. For example, it cannot be used to make signed URLs for listing objects in a bucket.

  • When specifying credentials, it is recommended that you identify your service account by using its email address; however, use of the service account ID is also supported.

Canonical requests

Signed URLs use canonical requests as part of the information encoded in their X-Goog-Signature query string parameter. When you make a signed URL with Cloud Storage tools, the required canonical request is created and incorporated automatically. However, when you make a signed URL with your own program, you need to define the canonical request yourself.

Credential scope

The credential scope appears in both the string-to-sign and the X-Goog-Credential query string parameter.

Signing strings with IAM signBlob

When generating a signed URL using a program, one option for signing the string is to use the IAM signBlob method provided by Google Cloud. The Signature that is output from this method is used when assembling the signed URL.

The signBlob service regularly rotates the private key that it uses. Signed URLs generated are usable for at least 12 hours, but may stop working prior to your set expiration time if the expiration time is greater 12 hours. Given this, signed URLs generated from signBlob are best used for short-lived access to resources.

What's next