Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Build Status Coverage Status


  • CIKit
  • Docker


Do not try to install the package separately! It's a submodule of CIKit.

Local or testing environment

cikit ssh
cd /var/www/cikit-rest-api
# Starts development server.
# Or `NODE_ENV=production npm start &` and `npm stop` to stop the server.
npm start

Stop the container.

cikit env/stop

Start existing container.

cikit env/start

Completely remove the container.

cikit env/rm

Run ESLint.

docker exec -i cikit-rest-api.loc bash -c 'cd /var/www/cikit-rest-api && npm run lint'

Run unit and functional tests.

docker exec -i cikit-rest-api.loc bash -c 'cd /var/www/cikit-rest-api && npm test'


Deploy to existing CIKit Matrix.

CIKIT_TAGS="api,ssl" cikit matrix/provision --limit=HOSTNAME --rest-api --ssl-src=/path/to/dir/with/ssl/crts

To deploy to a new Matrix remove the CIKIT_TAGS="api,ssl".

The /path/to/dir/with/ssl/certs must be a valid path to a directory that contains *.crt and *.key SSL certificates. They'll be copied to and used on a server by Nginx (for builds) and by Node.js (REST API server).

Update already deployed API

If CIKit Matrix already uses a REST API and got an update, you'll need to deploy the changes.

CIKIT_TAGS="api" cikit matrix/provision --limit=HOSTNAME --rest-api=deploy

User groups

  • viewer

    Can see the list of droplets.

  • manager

    Can manage (add/delete/start/stop/restart) droplets.

  • owner

    Single per system. Can do everything.

Every role inherits permissions from previous.



Get help.

node ./lib/cli/commands/create-user.js -h

Create an owner of the API (kinda super user that can be only one per system):

node ./lib/cli/commands/create-user.js -u BR0kEN -g owner

Note, that further attempts to create an owner will be declined.

Forcibly invalidate user's authentication token and regenerate a secret key.

node ./lib/cli/commands/create-user.js -u BR0kEN -g owner -r


Available endpoints


  • POST - /api/v1/user/auth - available for existing users of a system.

    Request an access token:

    curl http://localhost:1337/api/v1/user/auth -X POST -H "Content-Type: application/json" -d '{"username": "BR0kEN", "code": "172459"}'

    Response sample:

      "token_type": "Bearer",
      "expires_in": 7200,
      "access_token": "5e11d712066b99a9868888ec253c1979da9dc8f9823831262139f235ab9d64c3",
      "refresh_token": "3ead5fbb1a4e3953f855d84b304d96b08d10a83cad38ebc544832f2125293f2b"

    Add Authorization: Bearer: ACCESS_TOKEN header or {"access_token": "ACCESS_TOKEN"} to body for every request to an API. If you'll get 401, then the token is expired and you have to send a request for its refreshment (better flow is to store the expires_in in your implementation and check its validity before sending a request to an API).

  • POST - /api/v1/user/auth/refresh - can be accessed by existing user with valid refresh token.

    Refresh an existing access token using the refresh_token given after successful authentication:

    curl http://localhost:1337/api/v1/user/auth/refresh -X POST -H "Content-Type: application/json" -d '{"grant_type": "refresh_token", "refresh_token": "REFRESH_TOKEN"}'

    The structure of a response is the same as for previous API query.

  • DELETE - /api/v1/user/auth/revoke/:user - authorized owner can revoke for anyone, authorized users can revoke for ourselves.

    Revoke access and refresh tokens for a given user (require re-authentication).

    curl http://localhost:1337/api/v1/user/auth/revoke/BR0kEN -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer REFRESH_TOKEN"

    Response sample:

      "status": "ok"
  • GET - /api/v1/user/auth/setup/:user - authorized owner can request a QR code for setting up an authenticating application.

    curl http://localhost:1337/api/v1/user/auth/setup/BR0kEN -X GET -H "Content-Type: application/json" -H "Authorization: Bearer ACCESS_TOKEN"

    Response sample:

      "qr": "BASE64_ENCODED_PNG",
      "secret": "SECRET_KEY"
  • GET - /api/v1/user/list

  • POST - /api/v1/user/add

  • DELETE - /api/v1/user/delete/:user

The /api/v1/user/add and /api/v1/user/delete returns an updated list of users.


  • GET - /api/v1/droplet/list
  • POST - /api/v1/droplet/add
  • PATCH - /api/v1/droplet/stop/:droplet
  • PATCH - /api/v1/droplet/start/:droplet
  • PATCH - /api/v1/droplet/restart/:droplet
  • DELETE - /api/v1/droplet/delete/:droplet

All /api/v1/droplet/* endpoints returns a list of droplets. After add, stop, start, restart and delete an updated list will be returned.