This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Jikkou API Server Documentation

Learn Jikkou’s API Server usages.

Jikkou API Server provides a REST interface to any platform supported by Jikkou, making it even easier to manage, automate and visualise all your data platform assets.

Jikkou CLI can be used in combination with Jikkou API Server by configuring it in proxy mode. In this mode, the CLI no longer connects directly to your various platforms, but forwards all operations to the API server. This deployment method allows you to enhance the overall security of the platforms managed through Jikkou.

1 - Install Jikkou API Server

This guide shows how to install Jikkou API Server.


The latest stable release of Jikkou API Server is available:

Standalone Installation

Follow these few steps to download the latest stable versions and get started.


To be able to run Jikkou API Server, the only requirement is to have a working Java 21 installation. You can check the correct installation of Java by issuing the following command:

java -version

Step 1: Download

Download the latest Java binary distribution from the GitHub Releases (e.g.

Unpack the download distribution and move the unpacked directory to a desired destination

unzip jikkou-api-server-$
mv jikkou-api-server-$LATEST_VERSION /opt/jikkou

Step 2: Start the API Server

Launch the application with:


Step 3: Test the API Server

$ curl -sX GET http://localhost:28082 -H "Accept: application/json" | jq

  "version": "0.31.0",
  "build_time": "2023-11-14T18:07:38+0000",
  "commit_id": "dae1be11c092256f36c18c8f1d90f16b0c951716",
  "_links": {
    "self": {
      "href": "/",
      "templated": false
    "get-apis": {
      "href": "/apis",
      "templated": false

Step 4: Stop the API Server

PID=`ps -ef | grep -v grep | grep JikkouApiServer | awk '{print $2}'`
kill $PID


# Run Docker
docker run -it \
--net host \

Development Builds

In addition to releases you can download or install development snapshots of Jikkou API Server.

From Docker Hub

Docker images are built and push to Docker Hub from the latest main branch.

They are not official releases, and may not be stable. However, they offer the opportunity to test the cutting edge features.

$ docker run -it streamthoughts/jikkou-api-server:main

2 - Configurations

Learn how to configure Jikkou API Server.

Jikkou API Server is built with Micronaut Framework.

The default configuration file is located in the installation directory of you server under the path /etc/application.yaml.

You can either modify this configuration file directly or create a new one. Then, your configuration file path can be targeted through the MICRONAUT_CONFIG_FILES environment variable.

A YAML Configuration file example can be found here: application.yaml

2.1 - API Server

Learn how to configure the Jikkou API server.

Running Server on a Specific Port

By default, the server runs on port 28082. However, you can set the server to run on a specific port:

# ./etc/application.yaml
    port: 80  # Port used to access APIs

    port: 80  # Port used to access Health endpoints

Enabling Specific Extension Providers

By default, the server is configured to run only with the core and kafka extension providers. However, you can enable (or disable) additional providers:

    # By default, disable all extension providers.
    default.enabled: false
    # Explicitly enabled/disable an extension provider
    #<provider_name>.enabled: <boolean>
    core.enabled: true
    kafka.enabled: true
    # schemaregistry.enabled: true
    # aiven.enabled: true
    # kafkaconnect.enabled: true

2.2 - Authentication

Learn how to secure access to Jikkou API server.

Enable Security

To enable secure access to the API Server:

Configuration File

Update the configuration file (i.e., application.yaml) of the server with:

    enabled: true

Environment Variable

As an alternative, you can set the following environment variable MICRONAUT_SECUTIRY_ENABLED=true.

Unauthorized Access

When accessing a secured path, the server will return the following response if access is not authorized:

  "message": "Unauthorized",
  "errors": [
      "status": 401,
      "error_code": "authentication_user_unauthorized",
      "message": "Unauthorized"

2.2.1 - Basic Auth

Learn how to secure Jikkou API Server using Basic HTTP Authentication Scheme.

Jikkou API Server can be secured using a Basic HTTP Authentication Scheme.

RFC7617 defines the “Basic” Hypertext Transfer Protocol (HTTP) authentication scheme, which transmits credentials as user-id/password pairs, encoded using Base64.

Basic Authentication should be used over a secured connection using HTTPS.

Configure Basic HTTP Authentication

Step1: Enable security

Add the following configuration to your server configuration.

# ./etc/application.yaml
    enabled: true

Step2: Configure the list of users

The list of username/password authorized to connect to the API server can be configured as follows:

# ./etc/application.yaml
      - username: "admin"
        password: "{noop}password"

For production environment, password must not be configured in plaintext. Password can be passed encoded in bcrypt, scrypt, argon2, and sha256.


echo -n password | sha256sum
# ./etc/application.yaml
      - username: "admin"
        password: "{sha256}5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8"

Step3: Validate authentication

Encode credentials

echo -n "admin:password" | base64 

Send request

curl -IX GET http://localhost:28082/apis/ \
-H "Accept: application/json" \
-H "Authorization: Basic YWRtaW46cGFzc3dvcmQ"

HTTP/1.1 200 OK
Content-Type: application/hal+json
content-length: 576

2.2.2 - JWT

Learn how to secure Jikkou API Server using JWT (JSON Web Token) Authentication.

Jikkou API Server can be secured using JWT (JSON Web Token) Authentication.

Configure JWT

Step1: Set JWT signature secret

Add the following configuration to your server configuration.

# ./etc/application.yaml
    enabled: true
    authentication: bearer <1>
      enabled: true
              secret: ${JWT_GENERATOR_SIGNATURE_SECRET:pleaseChangeThisSecretForANewOne} <2>
  • <1> Set authentication to bearer to receive a JSON response from the login endpoint.
  • <2> Change this to your own secret and keep it safe (do not store this in your VCS).

Step2: Generate a Token

Generate a valid JSON Web Token on using your secret.

Example with pleaseChangeThisSecretForANewOne as signature secret.


Step3: Validate authentication

$ curl -I -X GET http://localhost:28082/apis/ \
-H "Accept: application/json" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.6cD3MnZmX2xyEAWyh-GgGD11TX8SmvmHVLknuAIJ8yE"

HTTP/1.1 200 OK
Content-Type: application/hal+json
content-length: 576

2.3 - CLI Proxy Mode

Learn how to configure Jikkou CLI in proxy mode.


Step 1: Enable Proxy Mode

To enable proxy mode so that the CLI communicates directly with your API Server, add the following parameters to your configuration:

jikkou {
  # Proxy Configuration
  proxy {
    # Specify whether proxy mode is enabled (default: false).
    enabled = true
    # URL of the API Server
    url = "http://localhost:28082"
    # Specifcy whether HTTP request debugging should be enabled (default: false)
    debugging = false
    # The connect timeout in millisecond (if not configured used ` default-timeout` ).
    connect-timeout = 10000
    # The read timeout in millisecond (if not configured used ` default-timeout` ).
    read-timeout = 10000
    # The write timeout in millisecond (if not configured used ` default-timeout` ).
    write-timeout = 10000
    # The default timeout (i.e., for read/connect) in millisecond (default: 10000)
    default-timeout = 10000
    # Security settings to authenticate to the API Server.
    security = {
      # For Token based Authentication.
      # access-token = ""
      # For Username/Password Basic-Authentication.
      # basic-auth = {
      #   username = ""
      #   password = ""
      # }

Step 2: Check connection

When enabling Proxy Mode, Jikkou CLI provides the additional command server-info. You can use it to verify the connectivity with teh server.

$ jikkou server-info -o JSON | jq

  "version": "0.31.0",
  "build_time": "2023-11-15T10:35:22+0100",
  "commit_id": "f3384d38e606fb32599c175895d0cbef28258540"

3 - Jikkou - API References

Jikkou - API References