OS secrets engine (API)

Use the OS secrets engine API to manage user credentials on remote hosts for RHEL systems. For general usage information, refer to the OS plugin overview.

Examples and API paths below assume you mounted the OS secrets engine on the default path (/os). If you configured the plugin with a custom path, update the endpoint call accordingly.

Configure top level parameters

Configure OS plugin setting for all hosts or accounts.

Parameters

• max_versions (int: 10): The number of secret versions to keep for each host account. The max version limit applies to all keys.
• ssh_host_key_trust_on_first_use (bool: false): Whether to allow trust-on-first-use ssh key adoption.

Sample payload

{
  "max_versions": 10,
  "ssh_host_key_trust_on_first_use": true
}

Sample request

$ curl \
    --header "X-Vault-Token: ${VAULT_TOKEN}" \
    --request POST \
    --data @payload.json \
    ${VAULT_ADDR}/v1/os/config

Read top level parameters

Display the current global configuration settings.

Sample request

$ curl \
    --header "X-Vault-Token: ${VAULT_TOKEN}" \
    ${VAULT_ADDR}/v1/os/config

Sample response

  {
  ...
    "data": {
      "max_versions": 10,
      "ssh_host_key_trust_on_first_use": true
    },
  ...
  }

Create Host

Configure or update the connection information used to communicate with the target host.

Path parameters

• name (string: <required>): Unique name for the target host configuration.

Request parameters

• address (string: <required>): Hostname or IPv4/IPv6 address of the target host.
• port (int: 22): Port number for SSH connection.
• ssh_host_key (string): Public key of the host in OpenSSH public key format.
• password_policy (string): Name of the Vault password policy that applies to all accounts under the target host.
• custom_metadata (map<string|string>): A map of arbitrary metadata strings that describe the secret. If an update call includes custom_metadata, Vault replaces the entire map.

• rotation_period (string/integer: 0) –
  Enterprise
  The amount of time, in seconds, Vault should wait before rotating the root credential. A zero value tells Vault not to rotate the root credential. The minimum rotation period is 10 seconds. You must set one of rotation_period or rotation_schedule, but cannot set both.
• rotation_schedule (string: "") –
  Enterprise
  The schedule, in cron-style time format, defining the schedule on which Vault should rotate the root token. Standard cron-style time format uses five fields to define the minute, hour, day of month, month, and day of week respectively. For example, 0 0 * * SAT tells Vault to rotate the root token every Saturday at 00:00. In 1.20.5 or later, Vault interprets the schedule in UTC. You must set one of rotation_schedule or rotation_period, but cannot set both.
• rotation_window (string/integer: 0) –
  Enterprise
  The maximum amount of time, in seconds, allowed to complete a rotation when a scheduled token rotation occurs. If Vault cannot rotate the token within the window (for example, due to a failure), Vault must wait to try again until the next scheduled rotation. The default rotation window is unbound and the minimum allowable window is 1 hour. You cannot set a rotation window when using rotation_period.
• disable_automated_rotation (bool: false) -
  Enterprise
  Cancels all upcoming rotations of the root credential until unset.

Host configured rotation fields will apply to all accounts under the target host that do not have explicit rotation values set.

Sample payload

{
  "address": "192.0.2.0",
  "port": 22,
  "ssh_host_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl",
  "password_policy": "short",
  "custom_metadata": {
    "foo": "bar",
    "baz": 67
  }
}

Sample request

$ curl \
    --header "X-Vault-Token: ${VAULT_TOKEN}" \
    --request POST \
    --data @payload.json \
    ${VAULT_ADDR}/v1/os/hosts/jumpbox

Read Host

Read the configuration of the host.

Sample request

$ curl \
    --header "X-Vault-Token: ${VAULT_TOKEN}" \
    ${VAULT_ADDR}/v1/os/hosts/jumpbox

Sample response

{
  ...
  "data": {
      "address": "192.0.2.0",
      "port": 22,
      "ssh_host_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl",
      "password_policy": "short",
      "custom_metadata": {
        "foo": "bar",
        "baz": 67
      }
  },
  ...
}

Delete Host

Delete the host entry in the plugin. It will fail if any accounts are associated with the host, unless the force parameter is provided.

Parametrs

name (string): the unique name for the host. force (bool): force the host to be deleted even if it has associated accounts. If provided, associated accounts will be deleted along with the host entry (this will not affect the remote host).

Sample request

$ curl \
    --header "X-Vault-Token: ${VAULT_TOKEN}" \
    --request DELETE
    ${VAULT_ADDR}/v1/os/hosts/jumpbox

List Hosts

List the names of configured hosts.

Sample request

$ curl \
    --header "X-Vault-Token: ${VAULT_TOKEN}" \
    --request LIST
    ${VAULT_ADDR}/v1/os/hosts

Sample response

{
  ...
  "data": {
    "keys": ["jumpbox"]
  },
  ...
}

Create Account

Configure an individual account on an existing host.

Parameters

• host_ref (string): Reference to the unique name for the host.
• name (string): The unique name for the account.
• username (string: <required>): The username of the local account.
• password (string: <required>): The initial password of the local account. Cannot be changed after creation via this path (see /reset).
• parent_account_ref (string): Reference to the name of the account for this host used to rotate this account. If not provided, this account will rotate its own credentials.
• password_policy (string): Name of a password policy. Will override any policy set in the associated host.
• custom_metadata (map<string|string>): A map of arbitrary string to string valued user-provided metadata meant to describe the secret. Note that on updates, the entire map will be replaced with the new map, if one is provided.
• verify_connection (bool: true): Specify whether to verify the connection to the remote host with the provided credentials when onboarding an account.

• rotation_period (string/integer: 0) –
  Enterprise
  The amount of time, in seconds, Vault should wait before rotating the root credential. A zero value tells Vault not to rotate the root credential. The minimum rotation period is 10 seconds. You must set one of rotation_period or rotation_schedule, but cannot set both.
• rotation_schedule (string: "") –
  Enterprise
  The schedule, in cron-style time format, defining the schedule on which Vault should rotate the root token. Standard cron-style time format uses five fields to define the minute, hour, day of month, month, and day of week respectively. For example, 0 0 * * SAT tells Vault to rotate the root token every Saturday at 00:00. In 1.20.5 or later, Vault interprets the schedule in UTC. You must set one of rotation_schedule or rotation_period, but cannot set both.
• rotation_window (string/integer: 0) –
  Enterprise
  The maximum amount of time, in seconds, allowed to complete a rotation when a scheduled token rotation occurs. If Vault cannot rotate the token within the window (for example, due to a failure), Vault must wait to try again until the next scheduled rotation. The default rotation window is unbound and the minimum allowable window is 1 hour. You cannot set a rotation window when using rotation_period.
• disable_automated_rotation (bool: false) -
  Enterprise
  Cancels all upcoming rotations of the root credential until unset.

Rotation fields set here will override any rotation settings configured on the associated host.

Sample payload

{
  "username": "dave",
  "password": "hunter2",
  "password_policy": "short",
  "parent_account_ref": "other_dave",
  "rotation_schedule": "0 0 1 * *",
  "custom_metadata": {
    "foo": "bar",
    "baz": 67
  }
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://127.0.0.1:8200/v1/os/hosts/jumpbox/accounts/dave

Read Account

Read the configuration of the account.

Parameters

• host_ref (string): Reference to the unique name for the host.
• name (string): The unique name for the account.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/os/hosts/jumpbox/accounts/dave

Sample response

{
  ...,
  "data": {
    "username": "dave",
    "last_vault_rotation": "2026-01-01T00:00:00Z",
    "next_vault_rotation": "2026-02-01T00:00:00Z",
    "parent_account_ref": "other_dave",
    "rotation_schedule": "0 0 1 * *",
    "password_policy": "short",
    "custom_metadata": {
      "foo": "bar",
      "baz": 67
    }
  },
  ...
}

Delete Account

Delete the account.

Parameters

• host_ref (string): Reference to the unique name for the host.
• name (string): The unique name for the account.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE
    http://127.0.0.1:8200/v1/os/hosts/jumpbox/accounts/dave

List Accounts

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST
    http://127.0.0.1:8200/v1/os/hosts/jumpbox/accounts/

Sample response

{
  ...
  "data": {
    "keys": ["dave", "other_dave"]
  },
  ...
}

Rotate Account Credential

This endpoint manually triggers a password rotation for a specific account on a target host. This is a synchronous operation; the request will block until the rotation process completes, the return code is verified, and the new password is saved.

Parameters

• host_ref (string): Reference to the unique name for the host.
• name (string): The unique name for the account.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST
    http://127.0.0.1:8200/v1/os/hosts/jumpbox/accounts/dave/rotate

Read Account Credential

This endpoint returns the password associated with a specific account on a target host.

Parameters

• host_ref (string): Reference to the unique name for the host.
• name (string): The unique name for the account.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/os/hosts/jumpbox/accounts/dave/creds

Sample response

{
  ...
  "data": {
    "username": "dave",
    "password": "xgzqdkpwid",
    "last_vault_rotation": "2026-02-01T00:00:00Z",
    "next_vault_rotation": "2026-03-01T00:00:00Z",
    "created_time": "2026-02-01T00:00:01Z",
    "ttl": 2246367,
    "version": 2
  },
  ...
}

Read Account Credential Versions

Parameters

• host_ref (string): Reference to the unique name for the host.
• name (string): The unique name for the account.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/os/hosts/jumpbox/accounts/dave/versions

Sample response

{
  ...
  "data": {
    "created_time": "2026-02-01T00:00:01Z",
    "ttl": 2242067,
    "current_version": 2,
    "versions": {
      "1": {
        "created_time": "2026-01-01T00:00:00Z",
        "expired_time": "2026-02-01T00:00:01Z"
      },
      "2": {
        "created_time": "2026-01-01T00:00:00Z"
      }
    }
  },
  ...
}

Restore Account Credential

This endpoint updates the current credential on the account to be equal to the value in the version specified. A new credential version is created.

NOTE: This does not change the credential on the remote host. It is intended to resolve scenarios where Vault has gotten out of sync with the remote host.

Parameters

• host_ref (string): Reference to the unique name for the host.
• name (string): The unique name for the account.
• version_id (string): The version of the credential to restore.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST
    http://127.0.0.1:8200/v1/os/hosts/jumpbox/accounts/dave/versions/1/restore

Reset Account Credential

This endpoint sets the account's credential to the provided value. A new credential version is created.

NOTE: This does not change the credential on the remote host. It is intended to resolve scenarios where the host's password had to be changed "out-of-band" and now Vault is out of sync with the remote host.

Parameters

• host_ref (string): Reference to the unique name for the host.
• name (string): The unique name for the account.
• password (string: <required>): The password of the account.

Sample payload

{
  "password": "password67"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://127.0.0.1:8200/v1/os/hosts/jumpbox/account/dave/reset