Programmable Media

Generating delivery URL signatures

Last updated: Jul-30-2024

Cloudinary delivery URLs require a signature component under the following circumstances:

  • Authenticated media assets - all assets uploaded with their type set to authenticated
  • Dynamic transformations with strict transformations enabled - this only applies to generating and then delivering new derived assets dynamically (on the fly).
  • Dynamic transformations with certain add-ons - this only applies if the add-on has never been used with the asset before. If you use a Cloudinary add-on that supports on-the-fly activation of the add-on capability in a transformation URL, check the relevant add-on documentation for the signature requirements.
  • Restricted image or video types - certain types of images or videos that are marked as restricted in the Security settings.

Automatically create a signed delivery URL

When generating a delivery URL using one of Cloudinary's backend SDKs, you can request to create a signature for the URL. For example, in Node.js, set the sign_url parameter to true. See the specific tab for the SDK you're interested in:

In this case, the generated Cloudinary URL includes a signature component (s--vnhlc4WH--).

Note
The tabs for the frontend SDKs show how to set a manually created signature in the URL.

You can also use the CLI to create signed URLs, using the -s option:

Manually create a signed delivery URL

Important
  • You can automatically generate the signature component using one of Cloudinary's backend SDKs.
  • api_secret, which is a required element of signature generation, should never be revealed to anyone who is not authorized, and therefore your signature should never be generated on the client side or inside your native application.

To manually create a signed delivery URL, you also need to create a signature component of the format /s--SIGNATURE--/ that is based on the Public ID and any transformations or version number you use in the rest of the delivery URL. The SIGNATURE is the first 8 characters of a URL-safe base64 message digest (hash value) created with an SHA (Secure Hash Algorithm) cryptographic function.

Note
By default, Cloudinary supports both SHA-1 and SHA-256 digests for validation, and you can use either. The SDK methods use the SHA-1 algorithm by default, but you can use the SHA-256 algorithm instead by setting the signature_algorithm SDK configuration parameter to sha256. If you want to limit your account to allow only the SHA-256 digest for all your validations, submit a request.

To generate the URL signature:

  1. Create a single string including all of the directives for the asset to deliver: any transformation parameters, the version number, the public_id, and file extension that will be used in the delivery URL, separating each component with slashes (/) (this string is exactly equivalent to the components of the delivery URL that will come after the signature).
  2. Append your API secret to the end of the string.
  3. Create a URL-safe base64 message digest (hash value) of the string using an SHA cryptographic function.

For example, if your API secret is abcd, and you need to generate a signature for the sample image scaled to 300x250, with a grayscale effect (w_300,h_250,e_grayscale), and delivered as a PNG:

  • Parameters to sign:
    • w_300,h_250,e_grayscale
    • sample.png
  • Parameters in a single string joined with a slash:
    • w_300,h_250,e_grayscale/sample.png
  • String including the API secret that is used to create the signature:
    • w_300,h_250,e_grayscale/sample.pngabcd
  • SHA-1 base64 result:
    • INQUGuluWsGzxkcBaITPo7KMKic
  • First 8 characters to use as URL signature:
    • INQUGulu
  • Full signature component including prefix and suffix:
    • s--INQUGulu--

The final delivery URL including the signature:

https://res.cloudinary.com/demo/image/upload/s--INQUGulu--/w_300,h_250,e_grayscale/sample.png

An example of the above in Ruby:

See also: Have a look at the Cloudinary Signatures quick reference for a summary of the payload string to sign for delivery URL signatures as well as information on other use cases that may require signature generation.

✔️ Feedback sent!

Rate this page: