# Service Mode REST API
## Keeper Commander Service Mode The Service Mode module for Keeper Commander enables REST API integration by providing a secure, configurable API server that can be deployed with minimal setup. This module allows users to execute Commander CLI commands through a REST API interface while maintaining security and configuration flexibility. The service can be run locally and it can optionally be integrated with Ngrok or Cloudflare tunnels for creating a routable address. ### Features #### Core Functionality * **API Server**: Flask-based REST API server for executing Commander CLI commands * **Service Management**: Complete lifecycle management for the API service * **Configuration Management**: Flexible configuration system with both interactive and streamlined setup options * **Security Controls**: Comprehensive security features including API key management, access controls, rate limiting and IP allow/deny * **API Versioning**: Two API versions supporting both synchronous (v1) and asynchronous (v2) operations * **Request Queue System**: Advanced asynchronous request processing with tracking and status monitoring * **Flexible Hosting Options**: Run on-prem, Docker container or in the cloud with integrated **Ngrok or Cloudflare tunnel** agent. #### Service Commands | Command | Description | | ---------------------- | ----------------------------------------------------------------- | | `service-create` | Initialize and configure the service with customizable settings | | `service-start` | Start the service with existing configuration | | `service-stop` | Gracefully stop the running service | | `service-status` | Display current service status | | `service-config-add` | Add new API configuration and command access settings | | `service-docker-setup` | Automated Docker service mode setup with KSM configuration | | `slack-app-setup` | Automated Slack App integration setup with Commander Service Mode | #### Security Features * API key authentication * Configurable token expiration (minutes/hours/days) * Optional AES-256 GCM encryption for API responses * TLS support with provided certificate (.pem) * Rate limiting with configurable rules * IP Allow list (whitelist) and IP Deny list (blacklist) management. * Request validation and policy enforcement * Local service config JSON or YAML file encryption using private key ### Security The Keeper Commander Service Mode feature is a self-hosted middleware that wraps an existing Commander session with a REST API. This feature is suited to environments where high speed requests and simple HTTPS-based APIs are desired. To ensure the most secure use of this feature, we recommend the following: * Use a service account dedicated to the Commander service, which is limited in scope to the necessary rights and capabilities. * Limit the scope of the Command access controls to only those commands which are required based on the use case. * Apply IP allowlist for accessing the REST API endpoint * Protect access to the machine running the Commander service * Use different API tokens for different commands and use cases ### Usage #### Basic Setup [Install Keeper Commander](https://docs.keeper.io/en/keeperpam/commander-cli/commander-installation-setup) and then login to the shell. 
keeper shell
Log in with your Keeper credentials when prompted. Since the Commander Service Mode is typically run as a service, it is recommended to use biometric login or a persistent login session. Biometric Login: ``` biometric register ``` Or create a persistent login session using the commands below: ``` this-device persistent-login on this-device register this-device timeout 30d this-device 2fa_expiration forever ``` #### Service Mode Create : Using Interactive Configuration Create and configure the service with interactive prompts: ``` service-create ``` You'll be prompted to configure: * Port number * Ngrok auth token (optional) * Cloudflare tunnel token (optional) * TLS certificate path (optional) * Request Queue system (y/n) * Security settings (optional) * Config format (yaml/json) (if not previously created) * Run mode (foreground/background) * Command access controls Example: Create Service Mode using TSL certificate (https) ``` My Vault> service-create Enter Port No:9090 Enable Ngrok Tunneling? (y/n):n Enable TLS Certificate (y/n):y Enter Certificate Path:/Users/cert/cert.pem Enter Certificate Password:/Users/cert/key.pem Enable Request Queue? (y/n):y Enable Advanced Security? (y/n):n Select Run Mode (foreground/background):foreground List of supported commands, Enter comma separated:whoami,record-add,tree,ls Select configuration format (json/yaml):yaml Generated API key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx Uploading service_config.yaml ... Commander Service starting on https://localhost:9090/api/v2/ Commander Service started with PID: 35215 ``` #### Streamlined Configuration: Configure the service quickly with a single command (default is foreground mode with http) : ``` service-create -p 9090 -c 'record-add,whoami' -f json ``` Configure the service quickly with **Ngrok** (providing Ngrok auth token and Ngrok subdomain) {% code overflow="wrap" %} ``` service-create -p 9090 -c 'record-add,whoami' -ng xxxxxxxxxxx -cd mydomain ``` {% endcode %} Configure the service quickly with **Cloudflare** (providing Cloudflare auth token and domain name) {% code overflow="wrap" %} ``` service-create -p 9090 -c 'record-add,whoami' -cf xxxxxxxxxxx -cfd myname ``` {% endcode %} Configure the service with advanced options: {% code overflow="wrap" %} ``` service-create -p -f -c -rm -q -crtf -crtp -aip -dip ``` {% endcode %} **Streamline Parameters**: * `-p, --port`: Port number for the service (required to trigger streamline configuration) * `-c, --commands`: Comma-separated list of allowed commands or aliases (required) * `-ng, --ngrok`: Ngrok authentication token for cloud managed URL access (Optional) * `-cd`: Ngrok custom domain, just subdomain portion (Optional) * `-cf,--cloudflare`: Cloudflare tunnel token for cloud managed URL access (Optional) * `-cfd`: Cloudflare custom domain (Optional) * `-crtf, --certfile`: SSL certificate file path, accepts `.crt`, `.pem` or `.key` (Optional) * `-crtp, --certpassword`: SSL certificate password (Optional) * `-q, --queue_enabled`: Enable request queue system (y/n) - **Default: y** * `-rm, --run_mode`: Service run mode (foreground/background) - **Default: foreground** * `-f, --fileformat`: Configuration file format (json/yaml) - The service checks the local config file and Vault for an existing configuration format before prompting for setup. * `-rl, --ratelimit`: Rate limit per endpoint per IP (e.g., `10/minute`, `100/hour`, `1000/day`) (Optional) * `-aip, --allowedip`: IP allow list (Optional) - **Default: 0.0.0.0/0,::/0** * `-dip`: Denied IP list (Optional) * `-ek, --encryption_key`: Base64-encoded 32-byte key for AES-256 response encryption (Optional) * `-te, --token_expiration`: API key expiration time (e.g., `30m`, `24h`, `7d`) (Optional) * `-ur, --update-record `: Store the generated API key and service URL in the specified vault record - Useful to hide API Key from logs (Optional) #### Configuration File After the initial configuration, Commander will create a record in the vault with the title of "Commander Service Mode". This record will contain a YAML/JSON file called `service_config`.

Commander Service Mode record

Subsequent startups require the `service-start` command with no parameters. Configuration is loaded from the local encrypted service\_config file. {% hint style="info" %} Although the config is stored securely in Vault, the service uses a locally cached encrypted file for startup. To force a reload from Vault, delete the local config file (\~/.keeper/service\_config.json or .yaml) before running service-start. {% endhint %} #### Example: Starting from the Terminal in the Foreground The service can be started from the system terminal. For example, the below command runs the `/api/v1` in foreground mode. (Enable queue mode (-q y) for /api/v2): {% code overflow="wrap" %} ``` keeper service-create -p 8090 -f json -c 'sync-down,whoami,record-add,login-status' -rm foreground -q n ``` {% endcode %} Ctrl-C will stop the service. Once the service has been created, subsequent terminal commands can just start up the service like this: 
 keeper service-start
If [biometric login](https://docs.keeper.io/en/keeperpam/commander-installation-setup/logging-in#logging-in-with-biometric-authentication) or [persistent login](https://docs.keeper.io/en/keeperpam/commander-installation-setup/logging-in#persistent-login-sessions-stay-logged-in) mode is enabled, the service startup is seamless. #### Service Management Check service status: ``` My Vault> service-status Current status: Commander Service is Running (PID: 12345, Terminal: /dev/ttys003) ``` Add additional configuration: ``` My Vault> service-config-add List of supported commands, Enter comma separated:tree Generated API key: XXXXXXXXXXXXXXXXXXX= Uploading service_config.yaml ... Config Record with API key created successfully. ``` Start the service: ``` My Vault> service-start Commander Service starting on https://localhost:8900/api/v2/ Commander Service started with PID: 12345 ``` Stop the service: ``` My Vault> service-stop Service stopped successfully ``` *** ### Health Check Commander Service Mode provides a health check URL for checking the service status. Example with the service running on localhost port 8080: Request: ``` curl http://localhost:8080/health ``` Response: ``` {"status":"ok"} ``` ### Support For support or feature requests, please [open a Github issue](https://github.com/Keeper-Security/Commander/issues) or contact: * Email: *** ### Next Steps * [API Usage](https://docs.keeper.io/en/keeperpam/commander-cli/service-mode-rest-api/api-usage) * [Service Tunneling](https://docs.keeper.io/en/keeperpam/commander-cli/service-mode-rest-api/service-tunneling) * [Docker Deployment](https://docs.keeper.io/en/keeperpam/commander-cli/service-mode-rest-api/docker-deployment) * [Advanced Settings](https://docs.keeper.io/en/keeperpam/commander-cli/service-mode-rest-api/advanced-settings)