Secure client side upload - V2 (beta)
You can upload files to the ImageKit.io media library directly from the client-side in Javascript or any client side application using JSON Web Token (JWT) authentication. You will need to implement authenticationEndpoint
endpoint on your backend server as shown here.
You can use ImageKit's JavaScript to get started quickly. See example usage.
This API is in beta and subject to change.
File size limit The maximum upload file size is limited to 25MB on the free plan. On paid plan, this limit is 300MB for video files.
Version limit A file can have a maximum of 100 versions.
Endpoint
Method | Endpoint |
---|---|
POST |
Request structure (multipart/form-data)
Parameter | Description |
---|---|
file required | This field accepts three kinds of values:
Note: When passing a URL in the file parameter, please ensure that our servers can access the URL. In case ImageKit is unable to download the file from the specified URL, a |
token required | This is the client-generated JSON Web Token (JWT). The ImageKit.io server uses it to authenticate and check that the upload request parameters have not been tampered with after the generation of the token. Learn how to create the token below on the page. Note: Sending a JWT that has been used in the past will result in a validation error. Even if your previous request resulted in an error, you should always send a new token. |
fileName required | The name with which the file has to be uploaded.
The file name can contain:
- Alphanumeric Characters: Any other character including space will be replaced by |
useUniqueFileName optional | Whether to use a unique filename for this file or not.
Default value - |
tags optional | Set the tags while uploading the file.
|
folder optional | The folder path (e.g. The folder name can contain:
- Alphanumeric Characters: Default value - / |
isPrivateFile optional | Whether to mark the file as private or not. This is only relevant for image type files
Default value - |
isPublished optional | Whether to upload file as published or not.
- Accepts |
customCoordinates optional | Define an important area in the image. This is only relevant for image type files.
|
responseFields optional | Comma-separated values of the fields that you want the API to return in the response. For example, set the value of this field to |
extensions optional | Stringified JSON object with array of extensions to be processed on the image. For reference about extensions read here. |
webhookUrl optional | Final status of pending extensions will be sent to this URL. To learn more about how ImageKit uses webhooks, refer here. |
overwriteFile optional | Default is |
overwriteAITags optional | Default is |
overwriteTags optional | Default is |
overwriteCustomMetadata optional | Default is |
customMetadata optional | Stringified JSON key-value data to be associated with the asset. Checkout |
transformation optional | Stringified JSON object with the properties:
|
Response code and structure (JSON)
In case of an error, you will get an error code along with the error message. On successful upload, you will receive a 200
status code with uploaded file details in a JSON-encoded response body.
Understanding response
The JSON-encoded response contains details of the file which can have the following properties:
Property name | Description |
---|---|
fileId | Unique |
name | Name of the file. |
filePath | The relative path of the file. In the case of an image, you can use this path to construct different transformations. |
tags | The array of tags associated with the image. If no tags are set, it will be |
AITags | Array of |
versionInfo | An object containing the file or file version's |
isPrivateFile | Is the file marked as private. It can be either |
customCoordinates | Value of custom coordinates associated with the image in the format |
url | A publicly accessible URL of the file. |
thumbnailUrl | In the case of an image, a small thumbnail URL. |
fileType | The type of file could be either |
height | Height of the media file in pixels (Only for images and videos) |
width | Width of the media file in pixels (Only for images and videos) |
size | Size of the file in Bytes |
bitRate | Bitrate of the media file (Only for videos) |
videoCodec | Video codec of the first stream for the media file (Only for videos) |
audioCodec | Audio codec of the first stream for the media file (Only for videos) |
duration | Duration of the media file content in seconds (Only for videos) |
customMetadata | A key-value data associated with the asset. Use |
embeddedMetadata | Consolidated embedded metadata associated with the file. It includes |
metadata | Metadata associated with the file in legacy format. |
extensionStatus | Extension names with their processing status at the time of completion of the request. It could have one of the following status values:
If no extension was requested, then this parameter is not returned. |
JSON Web Token (JWT) generation for client-side file upload
JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. Your backend should ideally implement an API that should provide token
. This is sent along with your upload request for authentication as well as validation of the integrity of upload parameters when using the upload API from the client side. Generating it requires your ImageKit.io private API key, and hence this should be generated on your backend. Learn more about JSON Web Token here.
JSON Web Token consist of three parts separated by dots-
Header
Payload
Signature
Header
The header of the JSON Web Tokens consists of three parts: the typ
of the token, which should be JWT
, the signing algorithm, alg
, being used, which is HMAC SHA256, and the kid
, which is your ImageKit account's public key.
Payload
The payload is the token's second component. This should include all of the upload parameters that you intend to provide in your upload file request. All arguments except file
and token
can be included in this payload. In your upload API request, you must include the same set of parameters and their associated values along with the 'file' and 'token'. If there is a mismatch between upload request parameter and their values and the ones in the payload used to generate JWT, the upload request will fail.
The key in the payload should be the parameter name, and the value should be in stringified form. If you want to send the 'fileName' and 'useUniqueFileName' parameters, for example, the payload will be:
Signature
To create the signature you have to take the encoded header, the encoded payload, your ImageKit.io account's private key and sign that using the HMAC SHA256 algorithm.
This is used to ensure that the payload was not altered along the route, as well as that the sender of the JWT is who they claim to be.
To create the JWT, the three outputs are transformed to Base64url strings and concatenated with periods (.). This JWT can then be used as a token
in the upload API request.
Never publish your private key on client-side The Private API key should be kept confidential and only stored on your own servers.
If you are using ImageKit.io JavaScript SDK for file upload, it requires an authenticationEndpoint
endpoint for getting authentication parameters required in the upload API.
How to implement authenticationEndpoint endpoint?
This endpoint is specified by authenticationEndpoint
parameter during initialization. The SDK sends an HTTP POST request to this endpoint and expects a JSON response having status code 200 containing the JWT in the token
field.
The request body structure looks like this:
Response structure:
Since calculating these parameters requires your ImageKit.io private API key, hence this endpoint has to be implemented on your server-side. You can implement this endpoint in any language of your choice. Below is an example of how to implement this endpoint in Node.js using jsonwebtoken.
Examples
The example below demonstrates only basic usage. Refer to these examples in the server-side upload section to learn about different use-cases. The only difference between client-side and server-side upload is how API authentication works.
Make sure you have implemented authenticationEndpoint
endpoint on your server as shown here before using the below examples.
Last updated