> This page is for Itential Platform On-Prem, version 6 (default).
> For other versions, use one of these documentation indexes:
> - 6 (default): https://docs.itential.com/itential-platform/6/llms.txt
> - 2023.2: https://docs.itential.com/itential-platform/2023-2/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Connect Platform to HashiCorp Vault

> Connect Itential Platform to a HashiCorp Vault server

This page explains how to connect Itential Platform to HashiCorp Vault. When you connect Platform to Vault, you manage secrets in one place and keep credentials out of Platform configuration files.

## Before you begin

Before you connect Platform to Vault, make sure you have the following.

### HashiCorp Vault requirements

* A running HashiCorp Vault installation. For instructions, see [Install Vault](https://developer.hashicorp.com/vault/docs/install) in the HashiCorp documentation.
* The kv-v2 secrets engine enabled. For instructions, see [KV secrets engine version 2](https://developer.hashicorp.com/vault/docs/secrets/kv/kv-v2) in the HashiCorp documentation.
* Authentication credentials, either a Vault token file or an AppRole `role_id` and `secret_id`.
* Network connectivity between Platform and your Vault server.

> **Info**
>
> Platform supports only the kv-v2 secrets engine.

### Platform requirements

* SSH access to the Platform servers.
* Write access to the `/etc/itential/platform.properties` file, or permission to set environment variables.

## Configure Platform

You can configure Platform to connect to Vault in any of the following ways:

* Set properties in the Platform properties file.
* Set environment variables. For a list of variables, see [Platform properties and environment variables reference](/itential-platform/6/configure/environment-variables-properties-reference).
* Configure a server profile in **properties.json**.

> **Warning**
>
> Platform 6 supports all three methods. Platform 2023.2 supports only the server profile (**properties.json**) method.

### Configuration parameters

| Properties file            | Environment variable                | Server profile          | Description                                                                                                   |
| -------------------------- | ----------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------- |
| `vault_url`                | `ITENTIAL_VAULT_URL`                | `vaultProps.url`        | The URL of the Vault server, including the hostname and port.                                                 |
| `vault_auth_method`        | `ITENTIAL_VAULT_AUTH_METHOD`        | `vaultProps.authMethod` | The authentication method, either `token` or `approle`. The default is `token`.                               |
| `vault_token`              | `ITENTIAL_VAULT_TOKEN`              | `vaultProps.token`      | The path to a file that contains the Vault authentication token. Required for token authentication.           |
| `vault_secrets_endpoint`   | `ITENTIAL_VAULT_SECRETS_ENDPOINT`   | `vaultProps.endpoint`   | The secrets engine mount point with `/data` appended, for example `kv-v2/data`.                               |
| `vault_read_only`          | `ITENTIAL_VAULT_READ_ONLY`          | `vaultProps.readOnly`   | When `true`, Platform reads secrets from Vault but doesn't write secrets back. The default is `true`.         |
| `vault_role_id`            | `ITENTIAL_VAULT_ROLE_ID`            | `vaultProps.role_id`    | The AppRole role ID. Required for AppRole authentication.                                                     |
| `vault_secret_id`          | `ITENTIAL_VAULT_SECRET_ID`          | `vaultProps.secret_id`  | The AppRole secret ID. Required for AppRole authentication.                                                   |
| `vault_approle_path`       | `ITENTIAL_VAULT_APPROLE_PATH`       | Not available           | The Vault path where the AppRole auth method is enabled. Platform 6 only.                                     |
| `vault_connection_timeout` | `ITENTIAL_VAULT_CONNECTION_TIMEOUT` | Not available           | The number of milliseconds to wait before a request to Vault times out. Platform 6 only.                      |
| `vault_namespace`          | `ITENTIAL_VAULT_NAMESPACE`          | Not available           | The Vault Enterprise namespace. Required only for multi-tenant Vault Enterprise deployments. Platform 6 only. |

> **Info**
>
> The `vault_secrets_endpoint` value must include `/data` after the mount point. For example, if your kv-v2 engine is mounted at `kv-v2`, set the endpoint to `kv-v2/data`. Platform prepends `/v1/` to build the full Vault API URL.

### Configuration examples

**`Properties file (Platform 6 only) - token auth`**

```properties title="Properties file (Platform 6 only) - token auth"
vault_url=https://vault.company.com:8200
vault_auth_method=token
vault_token=/opt/vault/token.txt
vault_secrets_endpoint=kv-v2/data
```

**`Properties file (Platform 6 only) - AppRole auth`**

```properties title="Properties file (Platform 6 only) - AppRole auth"
vault_url=https://vault.company.com:8200
vault_auth_method=approle
vault_role_id=cfb83d9f-fd94-e046-71e2-dcd51147288d
vault_secret_id=68df6e13-02b2-b60d-a39f-f8b879277d48
vault_secrets_endpoint=kv-v2/data
```

**`Environment variables (Platform 6 only) - token auth`**

```bash title="Environment variables (Platform 6 only) - token auth"
export ITENTIAL_VAULT_URL="https://vault.company.com:8200"
export ITENTIAL_VAULT_AUTH_METHOD="token"
export ITENTIAL_VAULT_TOKEN="/opt/vault/token.txt"
export ITENTIAL_VAULT_SECRETS_ENDPOINT="kv-v2/data"
```

**`Environment variables (Platform 6 only) - AppRole auth`**

```bash title="Environment variables (Platform 6 only) - AppRole auth"
export ITENTIAL_VAULT_URL="https://vault.company.com:8200"
export ITENTIAL_VAULT_AUTH_METHOD="approle"
export ITENTIAL_VAULT_ROLE_ID="cfb83d9f-fd94-e046-71e2-dcd51147288d"
export ITENTIAL_VAULT_SECRET_ID="68df6e13-02b2-b60d-a39f-f8b879277d48"
export ITENTIAL_VAULT_SECRETS_ENDPOINT="kv-v2/data"
```

**`Server profile (properties.json) - token auth`**

```json title="Server profile (properties.json) - token auth"
{
  "vaultProps": {
    "url": "https://vault.company.com:8200",
    "authMethod": "token",
    "token": "/opt/vault/token.txt",
    "endpoint": "kv-v2/data"
  }
}
```

**`Server profile (properties.json) - AppRole auth`**

```json title="Server profile (properties.json) - AppRole auth"
{
  "vaultProps": {
    "url": "https://vault.company.com:8200",
    "authMethod": "approle",
    "role_id": "cfb83d9f-fd94-e046-71e2-dcd51147288d",
    "secret_id": "68df6e13-02b2-b60d-a39f-f8b879277d48",
    "endpoint": "kv-v2/data"
  }
}
```

### Read-only mode

The `readOnly` property controls whether Platform can write secrets back to Vault.

When `readOnly` is `true`, which is the default:

* Platform retrieves secrets from Vault but doesn't write any values back.
* Automatic property encryption is disabled.

When `readOnly` is `false`, Platform stores sensitive adapter and integration properties directly in Vault as it processes them. We don't recommend this setting.

> **Warning**
>
> If you change `readOnly` from `false` to `true` after Platform stores secrets in Vault, those secrets become inaccessible. You must re-enter them manually in Itential.

## Verify the connection

After you configure Platform, verify that it can connect to Vault.

#### Restart Platform

Restart Platform to apply your configuration changes.

#### View the configuration

In Admin Essentials, view the read-only Vault configuration:

* **Platform 6:** Go to **Admin Essentials > Configuration**.
* **Platform 2023.2:** Go to **Admin Essentials > Profiles**.

#### Check the Platform logs

Check the Platform logs for Vault messages:

```bash
# Platform 6
sudo journalctl -u itential-platform -f | grep -i vault

# Platform 2023.2
sudo journalctl -u automation-platform -f | grep -i vault
```

Confirm that the logs show successful authentication and no connection errors.

#### Test secret retrieval

Retrieve a test secret to validate your setup. For instructions, see [Use secrets](/itential-platform/secrets/hashicorp/use).

## What's next

#### [Use secrets](/itential-platform/secrets/hashicorp/use)

Reference Vault secrets in your configurations.

#### [Troubleshoot](/itential-platform/secrets/hashicorp/monitor-troubleshoot)

Resolve common issues.