REST API

Users with paid plans can use unrestricted access to the CKBox REST API, allowing you for a more convenient integration with your application or automating you workflows.

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 tags, description, name, or any custom attributes
• Search within your assets

To read about the available REST API endpoints, please refer to the CKBox REST API documentation.

# 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 as for tokens that authenticate your users in CKBox. For more information about tokens, available fields, and examples of algorithms that produce JWT tokens, please refer to the Authentication article.

In the CKBox REST API, certain 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

The following properties must be included in the JWT token payload:

• aud – The environment ID, which is the identifier of the environment created in the CKEditor Ecosystem Dashboard.
• sub – The user ID, which is the unique identifier of the user for whom the token is issued.
• iat – A timestamp the token was issued at. Make sure that iat is present and contains the correct time stated in seconds. Some JWT implementations do not include it by default. Additionally, the system time may 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, all requests should be sent to the https://api.ckbox.io domain. Additionally, the token payload includes information about your environment ID, which is carried in the aud field. This enables the CKBox service to recognize requests intended for your specific CKBox environment.

For the purpose of this example, let’s assume that 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, as stated in the CKBox REST API documentation. 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 actual JWT token, and then send the request to the CKBox API endpoint. This should return a JSON containing the list of asset categories available in 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 CKBox REST API to obtain the list of asset categories.

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

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, please refer to the CKBox Code Examples repository.