---
title: Configuring System Secrets
description: By means of the REST API, System Secrets can be configured, and the
  current configuration can be retrieved.
pubDate: 2026-08-17T09:53:44.266Z
antora:
  editUrl: https://github.com/couchbase/docs-server/edit/release/7.6/modules/rest-api/pages/system-secrets-configuration.adoc
  xref: xref:7.6@server:rest-api:system-secrets-configuration.adoc[]
---

[Consult the llms.txt file for a full list of contents](/llms.txt)
[View original HTML](/server/7.6/rest-api/system-secrets-configuration.html)

# Configuring System Secrets

> By means of the REST API, System Secrets can be configured, and the current configuration can be retrieved. 

## [](#http-methods-and-uris)HTTP Methods and URIs

GET /nodes/self/secretsManagement

POST /node/controller/secretsManagement

## [](#description)Description

Configures _system secrets_; which comprises the master password, data keys, key storage, and the location of key-control scripts.

The **Full Admin**, **Local User Security Admin**, or **External User Security Admin** role is required.

## [](#curl-syntax)Curl Syntax

curl -X GET http://<ip-address-or-hostname>:8091/nodes/self/secretsManagement/encryptionService
  -u <username>:<password>

curl -X POST http://<ip-address-or-hostname>:8091/node/controller/secretsManagement/encryptionService
  -u <username>:<password>
  -H <header>
  [-d <option>=<value>]*

The `Content-Type` can be either `application/json` or `application/x-www-form-urlencoded`. (Note that `application/x-www-form-urlencoded` can be omitted in curl commands, since used by default.)

Each `option` and associated `value` is described below.

* `keyEncrypted`. Whether data keys should be encrypted by means of the master password. The value can be either `true` (the default) or `false`.
* `keyPath`. Specifies whether the data keys are stored at the default or at a custom location. The value can be either `auto` (which is the default) or `custom`. If the value is `auto`, the default location is used. If the value is `custom`, the path provided by `customKeyPath` is used. Note that this option is used only if `keyStorageType` has the value `file`.
* `customKeyPath`. A file-path that specifies a custom location at which the data keys are stored. This file-path is used only if the value of `keyPath` is `custom`.
* `keyStorageType`. The value can be `file` (which is the default) or `script`. If the value is `file`, the system stores the data keys in a file. If the value is `script`, a user-specified script is called, when keys are to be written, read, or deleted. These scripts must be specified by `writeCmd`, `readCmd`, and `deleteCmd`, respectively.
* `passwordSource`. The value can be `env` (which is the default) or `script`. If the value is `env`, the master password is read from the environment variable specified by `passwordEnv`. If the value is `script`, the master password is provided by the script specified by `passwordCmd`.
* `passwordEnv`. The name of the environment variable from which the master password is read (provided that the value of `passwordSource` is `env`). By default, the value of `passwordEnv` is `CB_MASTER_PASSWORD`.
* `passwordCmd`. The script to be executed for provision of the master password. This script is only executed when the value of `passwordSource` is `script`.  
This script is executed when the node is started. It may also be executed in the event either of a node-reconfiguration or of an anomaly. The script must exit with status code `0` — _otherwise, an error occurs_. The script is expected to write the master password to standard output.
* `passwordState`. Shows the state of the encryption-service master password and data keys. The value can be:

  * `default`. The encryption password is not set.
  * `user_configured`. The master password is set
  * `password_not_used`. The data keys are not encrypted.  
This is a read-only setting, and so cannot be used with the `POST` method.
* `readCmd`. The script to be executed for the reading of data keys (when the value of `keyStorageType` is `script`).
* `writeCmd`. The script to be executed for the writing of data keys (when the value of `keyStorageType` is `script`).
* `deleteCmd`. The script to be executed for the deletion of data keys (when the value of `keyStorageType` is `script`).

## [](#responses)Responses

For `GET` and `POST`, success returns `200 OK`, and an object containing the current settings.

Failure to authenticate returns `403 Bad Request`, and an error message such as the following:

{
  "message": "Forbidden. User needs the following permissions",
  "permissions": [
    "cluster.admin.security!write"
  ]
}

An incorrectly expressed URI returns `404 Object Not Found`. An incorrectly formatted payload returns `400 Bad Request`.

If an invalid or inaccessible script is specified for reading the master password for encryption-key handling, the call fails with `400 Bad Request`, and a corresponding error message.

## [](#examples)Examples

The following examples demonstrate different ways in which secrets management can be configured.

### [](#retrieving-the-current-configuration)Retrieving the Current Configuration

The following command retrieves the current configuration. Output is piped to the [jq](https://jqlang.github.io/jq/) command, to facilitate readability.

curl -v -X GET http://localhost:8091/nodes/self/secretsManagement/encryptionService \
-u Administrator:password | jq '.'

Output takes the following form:

{
  "keyEncrypted": true,
  "keyPath": "auto",
  "keyStorageType": "file",
  "passwordEnv": "CB_MASTER_PASSWORD",
  "passwordSource": "env",
  "passwordState": "default"
}

This output corresponds to the default settings.

### [](#specifying-a-custom-script-for-obtaining-the-master-pasword)Specifying a Custom Script for Obtaining the Master Pasword

The following call specifies, as the value of `passwordCmd`, a path to a custom script, and provides the script's required arguments.

curl -v -X POST http://localhost:8091/node/controller/secretsManagement/encryptionService \
-u Administrator:password \
-H "Content-Type:application/json" -s -d "$(cat)" | jq
{
    "keyEncrypted": true,
    "passwordSource": "script",
    "passwordCmd": "/home/vagrant/pwdScript.sh param1 param2"
} // Exit with ^D

If successful, the call returns `200 OK` and the following object, which confirms the new configuration.

{
  "keyEncrypted": true,
  "keyPath": "auto",
  "keyStorageType": "file",
  "passwordCmd": "/home/vagrant/pwdScript.sh param1 param2",
  "passwordSource": "script",
  "passwordState": "user_configured"
}

### [](#specifying-custom-scripts-for-handling-data-keys)Specifying Custom Scripts for Handling data keys

The following call specifies custom scripts for the reading, writing, and deleting of data keys:

curl -v -X POST http://localhost:8091/node/controller/secretsManagement/encryptionService \
-u Administrator:password \
-H "Content-Type:application/json" -s -d "$(cat)" | jq
{
    "keyStorageType": "script",
    "readCmd": "/home/vagrant/readScript.sh",
    "writeCmd": "/home/vagrant/writeScript.sh",
    "deleteCmd": "/home/vagrant/deleteScript.sh"
} // Exit with ^D

If the command is successful, output of the following form confirms the change in configuration:

{
    "deleteCmd": "/home/vagrant/deleteScript.sh",
    "keyStorageType": "script",
    "passwordState": "password_not_used",
    "readCmd": "/home/vagrant/readScript.sh",
    "writeCmd": "/home/vagrant/writeScript.sh"
}

### [](#re-establishing-the-default-configuration)Re-Establishing the Default Configuration

The following call re-establishes the default configuration.

curl -v -X POST http://localhost:8091/node/controller/secretsManagement/encryptionService \
-u Administrator:password \
-H "Content-Type:application/json" -s -d "$(cat)" | jq
{
    "keyStorageType": "file",
    "keyEncrypted": true,
    "passwordSource": "env",
    "passwordEnv": "CB_MASTER_PASSWORD"
  } // Exit with ^D

If successful, the call returns `200 OK`, and the following object, which confirms restoration of the default settings:

{
  "keyEncrypted": true,
  "keyPath": "auto",
  "keyStorageType": "file",
  "passwordEnv": "CB_MASTER_PASSWORD",
  "passwordSource": "env",
  "passwordState": "default"
}

## [](#designing-scripts-for-handling-data-keys)Designing Scripts for Handling data keys

Requirements for the behavior of customer scripts for reading, writing, and deleting data keys are described below. Note that the master password is _not_ used, when these commands are executed.

### [](#scripts-for-writing-data-keys)Scripts for Writing data keys

A custom script for writing data keys must accept at least one, and at most two arguments. The first (or only) argument is always the _main_ key to be used. If a second argument is provided, this is the _backup_ key, which is only used when the node rotates data keys. If two keys are specified, they should be separated by a space.

The following command would establish only the main key:

/home/vagrant/writeScript.sh BVegHS0+3jg/Ffn0inhJq6tuJRcOjnQNpBpyy6Cf45w=

The following command would establish both the main and the backup key:

/home/vagrant/writeScript.sh BVegHS0+3jg/Ffn0inhJq6tuJRcOjnQNpBpyy6Cf45w= \
UtCwS6mKnXJS1r76Rb6oDyITWi/XIuQia5/rcSiZvFY="

The script must exit with code `0`.

### [](#scripts-for-reading-data-keys)Scripts for Reading Data Keys

A custom script for reading data keys must return between zero and two keys, as follows.

If the custom script that is the value of `writeScript`:

* Has not yet been used, the script for reading exits with code `0`, and returns no key. For example:  
$ /home/vagrant/readScript.sh  
$
* Has written only one key (the _main_ key), the script for reading exits with code `0`, and returns the main key. For example:  
$ /home/vagrant/readScript.sh  
BVegHS0+3jg/Ffn0inhJq6tuJRcOjnQNpBpyy6Cf45w=  
$
* Has written _two_ keys (the _main_ and _backup_ keys), the script for reading exits with code `0`, and returns both keys. For example:  
$ /home/vagrant/readScript.sh  
BVegHS0+3jg/Ffn0inhJq6tuJRcOjnQNpBpyy6Cf45w= UtCwS6mKnXJS1r76Rb6oDyITWi/XIuQia5/rcSiZvFY="  
$

Note that the encryption-key format is opaque, and can only be created by the instance of Couchbase Server running on the node.

## [](#see-also)See Also

An overview of system secrets and their management, including an example of entering the master pasword at the system prompt, is provided in [Manage System Secrets](../manage/manage-security/manage-system-secrets.md).