Signatures

Last updated: Aug-03-2022

Cloudinary uses digital signatures both to verify the integrity of a message and to provide authentication for communicating over the Internet using the HTTP protocol. Signatures can help ensure that the message was not tampered with during transit and provide an additional layer of security to ensure that even if the transport channel has been compromised, the contents can still be verified.

Cloudinary's SDKs take care of the signature generation where needed for communication with Cloudinary, so you will only need to manually write the code for generating a signature when NOT using our SDKs or when you want to verify a signature that was sent from Cloudinary.

On this page:

The following table summarizes Cloudinary's signature usage and the payload signed in each case.

Signature usage Example use case Payload to sign
Generating authentication signatures Authenticating a POST request A string with the parameters used in the POST request to Cloudinary:

  • All parameters added to the method call should be included except: file, cloud_name, resource_type and your api_key.
  • Add the timestamp parameter.
  • Sort all the parameters in alphabetical order.
  • Separate the parameter names from their values with an = and join the parameter/value pairs together with an &.
Note: Separate multiple values for any array parameters with commas (e.g., public_ids=cat,dog,lion).
Verifying notification signatures Verifying a signature in the header of a notification sent from Cloudinary A string containing the entire response body with the X-Cld-Timestamp value appended on the end of the string.
Generating delivery URL signatures The signature component of a signed delivery URL of the format: /s--SIGNATURE--/ A string including all the components of the delivery URL that will come after the signature component.
Verifying signatures in the JSON response Verifying the signature parameter returned in the response to a method call. A string with the public_id and version parameters, separated from their values with an = and then joined together with an &.

Signature generation

To generate the signature, append your API secret to the end of the payload to sign described above, and then create a hexadecimal message digest (hash value) of the string using an SHA 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.

For example:

Using Cloudinary backend SDKs to generate SHA authentication signatures

You can use one of Cloudinary's backend SDKs to generate the authentication signature. The api_sign_request method uses 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. Make sure that the timestamp is included in the params_to_sign object.

The following Node.js app contains two examples of using the api_sign_request method to provide a signature for uploading files:

  • signed-uploads/modules/signuploadwidget.js provides a signature for uploading files using the upload widget (corresponding to signed-uploads/public/js/uploadclientwidget.js)
  • signed-uploads/modules/signuploadform.js provides a signature for uploading files using a form (corresponding to signed-uploads/public/js/uploadclientform.js)

Run the app
  1. Click Remix to Edit
  2. Enter your Cloudinary product environment credentials in signed-uploads/public/js/config.js
  3. Click View App
  4. Try both upload options

This code is also available in GitHub.

Important considerations for authentication signatures

When generating authentication signatures keep in mind the following:

  • The api_secret, which is a required element of the signature, 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.
  • For mobile and other client-side applications, you must either use unsigned upload or have a server for processing the signature.
  • Signatures are valid for one hour from the timestamp value used to generate the signature.
  • Make sure to regenerate the signature if you dynamically change the payload of an upload request.

See the Upload API reference for a list of API methods, parameters, and response samples.

111

✔️ Feedback sent!

Rate this page: