{"id":22665180,"url":"https://github.com/br0ken-/cikit-rest-api","last_synced_at":"2026-04-12T00:41:00.634Z","repository":{"id":31036664,"uuid":"126693918","full_name":"BR0kEN-/cikit-rest-api","owner":"BR0kEN-","description":"CIKit Matrix REST API","archived":false,"fork":false,"pushed_at":"2023-02-01T14:59:20.000Z","size":418,"stargazers_count":1,"open_issues_count":5,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-04T00:35:01.728Z","etag":null,"topics":["cikit","expressjs","nodejs","rest-api"],"latest_commit_sha":null,"homepage":"https://github.com/BR0kEN-/cikit","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BR0kEN-.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-03-25T12:11:52.000Z","updated_at":"2019-11-14T09:46:35.000Z","dependencies_parsed_at":"2023-02-19T19:30:45.946Z","dependency_job_id":null,"html_url":"https://github.com/BR0kEN-/cikit-rest-api","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BR0kEN-%2Fcikit-rest-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BR0kEN-%2Fcikit-rest-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BR0kEN-%2Fcikit-rest-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BR0kEN-%2Fcikit-rest-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BR0kEN-","download_url":"https://codeload.github.com/BR0kEN-/cikit-rest-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246165531,"owners_count":20734047,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cikit","expressjs","nodejs","rest-api"],"created_at":"2024-12-09T13:19:57.289Z","updated_at":"2026-04-12T00:41:00.598Z","avatar_url":"https://github.com/BR0kEN-.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CIKit Matrix REST API\n\n[![Build Status](https://travis-ci.org/BR0kEN-/cikit-rest-api.svg?branch=master)](https://travis-ci.org/BR0kEN-/cikit-rest-api)\n[![Coverage Status](https://coveralls.io/repos/github/BR0kEN-/cikit-rest-api/badge.svg?branch=master)](https://coveralls.io/github/BR0kEN-/cikit-rest-api?branch=master)\n\n## Requirements\n\n- CIKit\n- Docker\n\n## Installation\n\nDo not try to install the package separately! It's a submodule of [CIKit](https://github.com/BR0kEN-/cikit).\n\n### Local or testing environment\n\n```bash\n./start.sh\ncikit ssh\ncd /var/www/cikit-rest-api\n# Starts development server.\n# Or `NODE_ENV=production npm start \u0026` and `npm stop` to stop the server.\nnpm start\n```\n\nStop the container.\n\n```bash\ncikit env/stop\n```\n\nStart existing container.\n\n```bash\ncikit env/start\n```\n\nCompletely remove the container.\n\n```bash\ncikit env/rm\n```\n\nRun ESLint.\n\n```bash\ndocker exec -i cikit-rest-api.loc bash -c 'cd /var/www/cikit-rest-api \u0026\u0026 npm run lint'\n```\n\nRun unit and functional tests.\n\n```bash\ndocker exec -i cikit-rest-api.loc bash -c 'cd /var/www/cikit-rest-api \u0026\u0026 npm test'\n```\n\n### Production\n\nDeploy to existing CIKit Matrix.\n\n```bash\nCIKIT_TAGS=\"api,ssl\" cikit matrix/provision --limit=HOSTNAME --rest-api --ssl-src=/path/to/dir/with/ssl/crts\n```\n\n*To deploy to a new Matrix remove the `CIKIT_TAGS=\"api,ssl\"`.*\n\nThe `/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).\n\n### Update already deployed API\n\nIf CIKit Matrix already uses a REST API and got an update, you'll need to deploy the changes.\n\n```bash\nCIKIT_TAGS=\"api\" cikit matrix/provision --limit=HOSTNAME --rest-api=deploy\n```\n\n## User groups\n\n- `viewer`\n\n  Can see the list of droplets.\n\n- `manager`\n\n  Can manage (add/delete/start/stop/restart) droplets.\n\n- `owner`\n\n  Single per system. Can do everything.\n\n*Every role inherits permissions from previous.*\n\n## CLI\n\n### User\n\nGet help.\n\n```bash\nnode ./lib/cli/commands/create-user.js -h\n```\n\nCreate an owner of the API (kinda super user that can be only one per system):\n\n```bash\nnode ./lib/cli/commands/create-user.js -u BR0kEN -g owner\n```\n\n*Note, that further attempts to create an owner will be declined.*\n\nForcibly invalidate user's authentication token and regenerate a secret key.\n\n```bash\nnode ./lib/cli/commands/create-user.js -u BR0kEN -g owner -r\n```\n\n## API\n\n### Available endpoints\n\n#### User\n\n- `POST` - `/api/v1/user/auth` - available for existing users of a system.\n\n  Request an access token:\n\n  ```bash\n  curl http://localhost:1337/api/v1/user/auth -X POST -H \"Content-Type: application/json\" -d '{\"username\": \"BR0kEN\", \"code\": \"172459\"}'\n  ```\n\n  Response sample:\n\n  ```json\n  {\n    \"token_type\": \"Bearer\",\n    \"expires_in\": 7200,\n    \"access_token\": \"5e11d712066b99a9868888ec253c1979da9dc8f9823831262139f235ab9d64c3\",\n    \"refresh_token\": \"3ead5fbb1a4e3953f855d84b304d96b08d10a83cad38ebc544832f2125293f2b\"\n  }\n  ```\n\n  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).\n\n- `POST` - `/api/v1/user/auth/refresh` - can be accessed by existing user with valid refresh token.\n\n  Refresh an existing access token using the `refresh_token` given after successful authentication:\n\n  ```bash\n  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\"}'\n  ```\n\n  *The structure of a response is the same as for previous API query.*\n\n- `DELETE` - `/api/v1/user/auth/revoke/:user` - authorized owner can revoke for anyone, authorized users can revoke for ourselves.\n\n  Revoke `access` and `refresh` tokens for a given user (require re-authentication).\n\n  ```bash\n  curl http://localhost:1337/api/v1/user/auth/revoke/BR0kEN -X DELETE -H \"Content-Type: application/json\" -H \"Authorization: Bearer REFRESH_TOKEN\"\n  ```\n\n  Response sample:\n\n  ```json\n  {\n    \"status\": \"ok\"\n  }\n  ```\n\n- `GET` - `/api/v1/user/auth/setup/:user` - authorized owner can request a QR code for setting up an authenticating application.\n\n  ```bash\n  curl http://localhost:1337/api/v1/user/auth/setup/BR0kEN -X GET -H \"Content-Type: application/json\" -H \"Authorization: Bearer ACCESS_TOKEN\"\n  ```\n\n  Response sample:\n\n  ```json\n  {\n    \"qr\": \"BASE64_ENCODED_PNG\",\n    \"secret\": \"SECRET_KEY\"\n  }\n  ```\n\n- `GET` - `/api/v1/user/list`\n- `POST` - `/api/v1/user/add`\n- `DELETE` - `/api/v1/user/delete/:user`\n\nThe `/api/v1/user/add` and `/api/v1/user/delete` returns an updated list of users.\n\n#### Droplet\n\n- `GET` - `/api/v1/droplet/list`\n- `POST` - `/api/v1/droplet/add`\n- `PATCH` - `/api/v1/droplet/stop/:droplet`\n- `PATCH` - `/api/v1/droplet/start/:droplet`\n- `PATCH` - `/api/v1/droplet/restart/:droplet`\n- `DELETE` - `/api/v1/droplet/delete/:droplet`\n\nAll `/api/v1/droplet/*` endpoints returns a list of droplets. After `add`, `stop`, `start`, `restart` and `delete` an updated list will be returned.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbr0ken-%2Fcikit-rest-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbr0ken-%2Fcikit-rest-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbr0ken-%2Fcikit-rest-api/lists"}