> ## Documentation Index
> Fetch the complete documentation index at: https://cloudinary.com/documentation/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 have two options for authentication:

* **[Basic Authentication](image_upload_api_reference#basic_authentication)** (simpler): Authenticate Upload API requests using your API key and API secret via HTTP Basic Auth. No signature calculation required.
* **Signature-based authentication** (documented below): Generate a SHA signature manually or using a Cloudinary backend SDK signature generation method.

> **TIP**: For server-side Upload API calls, Basic Authentication is simpler than signature-based authentication because it doesn't require calculating timestamps or generating SHA signatures. For more information, see [Basic Authentication](image_upload_api_reference#basic_authentication) in the Upload API reference.

### 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.
> **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](cloudinary_sdks#configuration_parameters) to `sha256`. If you want to limit your account to allow only the SHA-256 digest for all your validations, [submit a request](https://support.cloudinary.com/hc/en-us/requests/new).

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:

 ```curl
curl -d "file=https://www.example.com/sample.jpg&api_key=1234&eager=w_400,h_300,c_pad|w_260,h_200,c_crop&public_id=sample_image&timestamp=1315060510&signature=bfd09f95f331f558cbd1320e67aa8d488770583e" -X POST http://api.cloudinary.com/v1_1/demo/image/upload
 ```

> **NOTE**: The body of the POST request must be stringified, as seen in the example above (all parameters are included as a single string, even when the content type is JSON).

 Or, using the POST request from the [form example](client_side_uploading#code_explorer_upload_multiple_files_using_a_form_unsigned) with a selected local file:

```
...
    formData.append("file", file);
    formData.append("api_key", "1234");
    formData.append("eager", "w_400,h_300,c_pad|w_260,h_200,c_crop");
    formData.append("public_id", "sample_image");
    formData.append("timestamp", "1315060510");
    formData.append("signature", "bfd09f95f331f558cbd1320e67aa8d488770583e");
 
    fetch(url, {
      method: "POST",
      body: formData
    })
...
```

> **See also**:
>
> Have a look at the [Cloudinary Signatures](signatures) quick reference for a summary of the payload string to sign for authentication signatures as well as information on other use cases that may require signature generation.

### 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](cloudinary_sdks#configuration_parameters) to `sha256`. Make sure that the timestamp is included in the `params_to_sign` object.

```multi
|ruby 
Cloudinary::Utils.api_sign_request(params_to_sign, api_secret)

|php_2
ApiUtils::signRequest($paramsToSign, $cloudConfig);

|python
cloudinary.utils.api_sign_request(params_to_sign, api_secret)

|nodejs
cloudinary.utils.api_sign_request(params_to_sign, api_secret);

|java
cloudinary.apiSignRequest(Map<String, Object> paramsToSign, String apiSecret);

|csharp
cloudinary.Api.SignParameters(IDictionary<string, object> parameters);

|go
resp, err := api.SignParameters(ParamsToSign, APISecret)

|cli
cld utils api_sign_request $params_to_sign $api_secret
```

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](https://github.com/cloudinary-devs/cld-signed-upload-examples/blob/main/signed-uploads/modules/signuploadwidget.js) provides a signature for uploading files using the upload widget (corresponding to [signed-uploads/public/js/uploadclientwidget.js](https://github.com/cloudinary-devs/cld-signed-upload-examples/blob/main/signed-uploads/public/js/uploadclientwidget.js))
* [signed-uploads/modules/signuploadform.js](https://github.com/cloudinary-devs/cld-signed-upload-examples/blob/main/signed-uploads/modules/signuploadform.js) provides a signature for uploading files using a form (corresponding to [signed-uploads/public/js/uploadclientform.js](https://github.com/cloudinary-devs/cld-signed-upload-examples/blob/main/signed-uploads/public/js/uploadclientform.js))

#### Setup instructions (after cloning from GitHub)

1. Install all dependencies from the top level:
   
    ```Terminal
    npm install
    ```
1. Open **signed-uploads/public/js/config.js**
1. Set `cloud_name`, `api_key` and `api_secret` with the corresponding account details from the [API Keys](https://console.cloudinary.com/app/settings/api-keys) page of the Console Settings.
1. Run the app to start the server:
    
      ```Terminal
      node signed-uploads/app.js
      ```

      The response should be:

      ```Terminal
      Server is up on http://localhost:3000
      ```
1. Open `http://localhost:3000` in a browser.

Go to [GitHub](https://github.com/cloudinary-devs/cld-signed-upload-examples) to try it out:

  
  
  
 

> **See also**:
>
> Watch this [video tutorial](generate_upload_signature_tutorial) explaining how to generate a signature using the Node.js SDK for use in a direct call to the REST API.

### 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](https://support.cloudinary.com/hc/en-us/articles/202519952-How-to-dynamically-change-the-payload-of-a-jQuery-direct-upload-request-).

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