CKBox REST API

CKBox offers a REST API for more convenient integration with your application and workflow automation. It is useful for migration from another digital asset manager, mass upload or modification of assets and their metadata, or when you want to interact with your assets without using the UI.

With the REST API, you can:

• Upload and manage assets in CKBox.
• Download assets.
• Manage your folders.
• Create asset categories and change their configuration.
• Move and copy assets between folders.
• Resize images and automatically convert them to any of the supported formats (webp, jpeg, png, gif, tiff).
• Control the quality of images produced by CKBox.
• Fetch the list of recently used assets for a given user.
• Fetch and modify asset metadata, such as the tags, description, name, or any custom attributes.
• Search within your assets.

Refer to the CKBox REST API documentation to read about the available REST API endpoints.

# Connecting to the REST API

# Authentication

Authentication for requests to the CKBox REST API requires a JWT token. This token must be included in the Authorization header of the requests.

To create a JWT token for authentication, use the same algorithm like for tokens that authenticate your users in CKBox. Refer to the Authentication guide for more information about tokens, available fields, and examples of algorithms that produce JWT tokens.

In the CKBox REST API, some endpoints require the admin user role to be present in the token. To use all available endpoints when communicating with the API, you should use tokens with auth.ckbox.role set to admin in the token payload.

Here is an example of the token payload required to authenticate requests sent to the CKBox REST API that grants access to all endpoints, including those that perform actions of the administrator user:

{
    "aud": "NQoFK1NLVelFWOBQtQ8A",
    "sub": "example-user-id",
    "iat": 1511963669,
    "auth": {
        "ckbox": {
            "role": "admin"
        }
    }
}

# Payload properties

You must include the following properties in the JWT token payload:

• aud – The environment ID. This is the identifier of the environment created in the Customer Portal.
• sub – The user ID. This is the unique identifier of the user for whom the token is issued.
• iat – A timestamp the token was issued at. Ensure that iat is present and contains the correct time given in seconds. Some JWT implementations do not include it by default. The system time may also be invalid, causing strange issues with tokens (see, for example, Docker for Mac time drift).
• auth – An object defining the user’s role. Allowed values are user for regular users and admin for administrator users.

# Sending request

To interact with the CKBox service, send all the requests to the https://api.ckbox.io/ domain. Additionally, the token payload includes information about your environment ID carried in the aud field. It enables the CKBox service to recognize requests intended for your specific CKBox environment.

In this example, let’s assume you want to fetch a list of all asset categories available in your CKBox instance. To obtain this information, you can use the GET /categories endpoint. Assuming that you have already created a valid JWT token to authenticate the request, your request should look like the following:

curl 'https://api.ckbox.io/categories' -H 'Authorization: <jwt_token>'

Replace the <jwt_token> placeholder with your JWT token and send the request to the CKBox API endpoint. It should return a JSON containing the list of asset categories from your CKBox environment.

# Example application

Below you can find a complete code of an example for Node.js. The code signs a JWT token with the required payload and then sends the request to the CKBox REST API to obtain the list of asset categories.

Before you run this code, replace <environment_id> and <access_key> with the environment ID and access key obtained in the Customer Portal.

const jwt = require('jsonwebtoken');
const axios = require('axios');

const ENVIRONMENT_ID = '<your_environment_id>'; // Provide your environment ID.
const ACCESS_KEY = '<your_access_key>';         // Provide your access key.

const getToken = (userId, role) => {
    return jwt.sign(
        {
            aud: ENVIRONMENT_ID,
            sub: userId,
            auth: {
                ckbox: {
                    role
                }
            }
        },
        ACCESS_KEY,
        {
            algorithm: 'HS256'
        }
    );
};

axios.get('https://api.ckbox.io/categories', {
        headers: {
            Authorization: getToken('dummy-admin-id', 'admin')
        }
    })
    .then(response => console.dir(response.data, { depth: 5 }))
    .catch(error => console.error(error.response.data));

For a complete working example, refer to the CKBox Code Examples repository.