Signed URLs

A signed URL is a secure URL that can be generated only by you using your account's private key. There are certain use cases where you will need to use signed URLs:

  • You have turned on the "Restrict unsigned URLs" setting from the dashboard.

  • You watermark all your images using ImageKit.io parameters to protect original assets. You do not want anyone to access the original image by removing the watermark specific transformation from the image URL.​

  • You want certain image URLs in your application to be accessible only for a specific time period in the future.

  • You are trying to access a private image.

When generating signed URLs, use the private key available within the Developer section on the dashboard. Signing the URLs adds additional query parameters to ensure that image transformations cannot be altered from the URL. If someone tries to modify the image transformation or the image URL or use it beyond its intended expiry time, a 401 Unauthorised response status code is returned.

A signed URL would be similar to :

https://ik.imagekit.io/your_imagekit_id/path-to-image.jpg?ik-s=generatedURLsignature&ik-t=UTCtimestamp

If you want to create a signed URL that uses a Web Proxy origin, you must encode the complete URL of the input image before signing it. For example, instead of using https://example.com/image.jpgas input for the signed URL, you should use https%3A%2F%2Fexample.com%2Fimage.jpg.

Generating Signed URLs

You can create a signed URL using server-side SDKs.

var imageURL = imagekit.url({
    path : "/default-image.jpg",
    queryParameters : {
        "v" : "123"
    },
    transformation : [{
        "height" : "300",
        "width" : "400"
    }],
    signed : true,
    expireSeconds : 300
});

Pseudo-code for signed URL generation

If you want to generate the signed URL yourself, refer to the pseudo-code below.

The value of signature i.e. ik-s should be in lowercase.

// Assume we have an image URL
var imageUrl = "https://ik.imagekit.io/your_imagekit_id/tr:w-400:rotate-91/sample/testing-file.jpg";

// This is our endpoint
var urlEndpoint = "https://ik.imagekit.io/your_imagekit_id";

// Make sure urlEndpoint has a trailing slash (/)
if(urlEndpoint[urlEndpoint.length - 1] != "/") {
    urlEndpoint = urlEndpoint + "/"
}

// Let's say we want to expire image in 300 seconds, so expireTimestamp (UTC timestamp) would be
var expiryTimestamp = parseInt(new Date().getTime() / 1000, 10) + 300;

// Remove the urlEndpoint from image URL
var str = imageUrl.replace(urlEndpoint,"");
// str will be tr:w-400:rotate-91/sample/testing-file.jpg

// Append the expiryTimestamp in above str
str = str + expiryTimestamp
// str will be tr:w-400:rotate-91/sample/testing-file.jpg9999999999

// Calcualte the signature using your priviate key 
var signature = crypto.createHmac('sha1', "your_private_key").update(str).digest('hex');

// Add ik-t and ik-s query parameters in the url
var finalImageUrl = imageUrl + "?ik-t=" + expiryTimestamp + "&ik-s=" + signature;

Signed URLs with special characters and diacritics

Most browser engines encode special characters, diacritics or characters from different charsets to UTF-8. For example, (diacritic) is encoded as e%CC%81, and so on.

To ensure that your signed URLs that contain such characters work, you must encode the complete URL of the input image before signing it. For example, instead of using /default-image-with-é.jpg as input path for the signed URL, use /default-image-with-e%CC%81.jpg.

/**
 * In this case, encodeURIComponent(...) will return the UTF-8 equivalent -
 * "/default-image-with-e%CC%81.jpg", which is then used for signing.
 * 
 * Ref: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent
 **/
var imageURL = imagekit.url({
    path : encodeURIComponent("/default-image-with-é.jpg"),
    queryParameters : {
        "v" : "123"
    },
    transformation : [{
        "height" : "300",
        "width" : "400"
    }],
    signed : true,
    expireSeconds : 300
});

Last updated