Programmable Media
Menu

Generating delivery URL signatures

Last updated: Dec-11-2023

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

  • Authenticated media assets - all assets uploaded with their resource_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.

On this page:

Manually create a signed delivery URL

Important
  • The signature component is automatically generated and added to the URL when you use one of Cloudinary's SDK helper methods and you include the sign_url boolean parameter set to true.
  • api_secret, which is a required element of in 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: