Generating authentication signatures

When using the Cloudinary SDKs for any upload or admin method that requires a signature, the signature is automatically generated and added to the request. If, however, you are making direct calls to the REST API, you need to generate a signature yourself. You can do this manually, or by using a Cloudinary backend SDK signature generation method.

Manual signature generation

If you manually generate your own POST request, you need to authenticate the request with a signature based on the parameters you use in the request. The signature is a hexadecimal message digest (hash value) created with the SHA-1 or SHA-256 (Secure Hash Algorithm) cryptographic function.

1. Create 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 &.
2. Append your API secret to the end of the string.
3. Create a hexadecimal message digest (hash value) of the string using an SHA cryptographic function.

For example, if your API secret is abcd, your API key is 1234, the Unix time now is 1315060510 and you are posting a request to upload a file from 'https://www.example.com/sample.jpg', set its public ID as sample_image, and eagerly generate 2 images:

• Parameters to sign:
  • timestamp: 1315060510
  • public_id: sample_image
  • eager: w_400,h_300,c_pad|w_260,h_200,c_crop
• Serialized sorted parameters in a single string:
  • eager=w_400,h_300,c_pad|w_260,h_200,c_crop&public_id=sample_image&timestamp=1315060510
• String including the API secret that is used to create the SHA-1 signature:
  • eager=w_400,h_300,c_pad|w_260,h_200,c_crop&public_id=sample_image&timestamp=1315060510abcd
• SHA-1 hexadecimal result:
  • bfd09f95f331f558cbd1320e67aa8d488770583e

The final request parameters for the upload POST request:

• timestamp: 1315060510
• public_id: sample_image
• api_key: 1234
• eager: w_400,h_300,c_pad|w_260,h_200,c_crop
• file: https://www.example.com/sample.jpg
• signature: bfd09f95f331f558cbd1320e67aa8d488770583e

For example, combining all the parameters in a cURL POST request to the demo product environment:

Or, using the POST request from the form example with a selected local file:

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)

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.