Signed URLs

Signed URLs allow converting files on demand only using URL query parameters. As the signed URLs are publicly visible, they don't use your API key and use an encrypted signature instead.

For example, this feature is useful to build "Download as PDF" buttons easily without the need of a complete API integration.

Example Signed URL

https://s.cloudconvert.com/b3d85428-584e-4639-bc11-76b7dee9c109
?job=eyJ0YXNrcyI6eyJpbXBvcnQtaX...&s=69e56b8fead...

Create a signed URL

First, you need to create a signed URL base using your dashboard. Using this signed URL base you can create dynamic signed URLs using the following URL parameters.

Second, you can use the "Generate Signed URL" button on your dashboard to use a simple graphical interface for creating signed URLs. Alternatively, you can build dynamic signed URLs via code as described below.

We recommend using our official SDKs to create the signed URls, as shown on the right. All our SDKs have built functions to properly generate the query parameters and signatures of the signed URLs.

Do not include any sensitive information in the job payload (such as S3 credentials)! The job payload can be extracted from the URL.

Each request to a signed URL starts a new job and therefore consumes credits by default. Therefore, make sure you are using the cache_key parameter to start a job only once every 24h.

Query Parameters
job string, required

The Base64-encoded JSON job payload. This is the same payload, you would regularly send as body to the /jobs endpoint. The job is required to have an export/url task which will automatically used to redirect to.

Please make sure you are using URL-safe Base64 encoding, where the '+' and '/' characters of standard Base64 are respectively replaced by '-' and '_'.

cache_key string, optional

By default, the output files of signed URLs will not be cached and each request to the URL starts a new job. When using cache_key, the output files will be cached based on the specified key for 24 hours.

This parameter on the one hand speeds up subsequent requests to the same URL and one the other hand it reduces costs by only doing the conversion once for 24h.

Only alphanumeric characters, - and _ are allowed as cache key.

s string, required

The signature which is calculated using HMAC with SHA-256.

Each signed URL base has an unique signing secret to generate the signature. You can show the signing secret of your signed URL base in your signed URL settings using the button.

The signature is a hash over the URL (signed URL base including query parameters, except &s). The generated signature is then appended as &s= as the last parameter in your URLs.

As an example, the following PHP function calculates the signature:

$signature = hash_hmac('sha256', $url, $signingSecret);

Signed URL response

If successful, it redirects to the output file of the conversion (a 302 redirect with the Location header pointing to the output file).

If the conversion fails, the job status payload will be returned as JSON.

PHP Code

<?php

$cloudconvert = new CloudConvert([
    'api_key' => 'API_KEY',
    'sandbox' => false
]);

$job = (new Job())
    ->addTask(
        (new Task('import/url', 'import-my-file'))
            ->set('url', 'https://my.url/file.docx')
    )
    ->addTask(
        (new Task('convert', 'convert-my-file'))
            ->set('input', 'import-my-file')
            ->set('output_format', 'pdf')
    )
    ->addTask(
        (new Task('export/url', 'export-my-file'))
            ->set('input', 'convert-my-file')
    );

$signedUrlBase = 'SIGNED_URL_BASE';
$signingSecret = 'SIGNED_URL_SIGNING_SECRET';
$url = $cloudConvert->signedUrlBuilder()->createFromJob($signedUrlBase, $signingSecret, $job, 'CACHE_KEY');

node.js Code

const signedUrlBase = 'https://s.cloudconvert.com/...'; // You can find it in your signed URL settings.
const signingSecret = '...'; // You can find it in your signed URL settings.
const cacheKey = 'cache-key'; // Allows caching of the result file for 24h

const job = {
    tasks: {
        'import-it': {
            operation: 'import/url',
            url: 'https://some.url',
            filename: 'logo.png'
        },
        'export-it': {
            operation: 'export/url',
            input: 'import-it',
            inline: true
        }
    }
};

const url = cloudConvert.signedUrls.sign(
    signedUrlBase,
    signingSecret,
    job,
    cacheKey
); // returns the generated URL

Python Code

base = 'https://s.cloudconvert.com/...'  # You can find it in your signed URL settings.
signing_secret = '...'  # You can find it in your signed URL settings.
cache_key = 'cache-key'  # Allows caching of the result file for 24h

job = {
    "tasks": {
        "import-file": {
            "operation": "import/url",
            "url": "https://github.com/cloudconvert/cloudconvert-php/raw/master/tests/Integration/files/input.pdf"
        },
        "export-file": {
            "operation": "export/url",
            "input": "import-file"
        }
    }
}

url = cloudconvert.SignedUrl.sign(base, signing_secret, job, cache_key);  # returns the URL

Ruby Code

base = 'https://s.cloudconvert.com/...' # You can find it in your signed URL settings.
signing_secret = '...' # You can find it in your signed URL settings.
cache_key = 'cache-key' # Allows caching of the result file for 24h

job = {
  tasks: {
    "import-it": { operation: "import/url", filename: "test.file", url: "http://invalid.url" },
    "convert-it": { input: "import-it", operation: "convert", output_format: "pdf" },
  }
}

url = CloudConvert::SignedUrl.sign(base, signing_secret, job, cache_key)

Java Code

final String base = "https://s.cloudconvert.com/..."; // You can find it in your signed URL settings.
final String signingSecret = "..."; // You can find it in your signed URL settings.
final String cacheKey = "mykey"; // Allows caching of the result file for 24h

final Map<String, TaskRequest> tasks = ImmutableMap.of(
        "import-my-file", new UrlImportRequest().setUrl("import-url"),
        "convert-my-file", new ConvertFilesTaskRequest()
        .setInput("import-my-file")
        .setOutputFormat("pdf")
        "export-my-file", new UrlExportRequest().setInput("convert-my-file")
        );


final String url = cloudConvertClient.signedUrls().sign(base, signingSecret, tasks, cacheKey);

C# Code

var signedUrlBase = 'https://s.cloudconvert.com/...'; // You can find it in your signed URL settings.
var signingSecret = '...'; // You can find it in your signed URL settings.
var cacheKey = 'cache-key'; // Allows caching of the result file for 24h

var job = new JobCreateRequest
      {
        Tasks = new
        {
          import_example_1 = new ImportUploadCreateRequest(),
          convert = new ConvertCreateRequest
          {
            Input = "import_example_1",
            Input_Format = "pdf",
            Output_Format = "docx"
          },
          export = new ExportUrlCreateRequest
          {
            Input = "convert"
          }
        },
};

string signedUrl = _cloudConvertAPI.CreateSignedUrl(baseUrl, signingSecret, job, cacheKey)
// returns the signed URL