Skip to main content

​
Introduction

The HashiCorp Vault integration lets Rootly securely read secrets from your Vault cluster and make them available in workflow actions via Liquid templating. Instead of hardcoding sensitive values — API keys, tokens, passwords — in your workflow configurations, you define named secret references that are resolved at runtime from Vault.
Rootly only supports the KV Secrets Engine version 2. KV v1 and other secret engines (AWS, PKI, Transit, etc.) are not currently supported.

​
Before You Begin

Before setting up the HashiCorp Vault integration, make sure you have:
  • A Rootly account with owner or admin permissions
  • A running HashiCorp Vault cluster accessible over HTTPS (or HTTP for internal deployments)
  • An AppRole configured in Vault with a role_id and secret_id — Rootly authenticates exclusively via the AppRole auth method
  • The namespace your AppRole is configured in (enterprise Vault deployments)
  • The mount path and path of the KV v2 secrets you want to expose to Rootly
Only the AppRole auth method is supported. If you need another auth method (token, Kubernetes, AWS IAM, etc.), contact support@rootly.com.

​
Installation

Open the integrations page in Rootly

Navigate to the integrations page in your Rootly workspace and select HashiCorp Vault.
HashiCorp Vault integration setup

Enter your Vault credentials

Fill in the following fields:
FieldDescription
Instance URLYour Vault server URL — e.g., https://vault.yourcompany.com. Trailing slashes are stripped automatically.
NamespaceYour Vault namespace. For Vault Enterprise, this is typically admin or a child namespace. Required.
Role IDThe role_id from your AppRole configuration in Vault. Encrypted at rest in Rootly.
Secret IDThe secret_id from your AppRole configuration in Vault. Encrypted at rest in Rootly.
HashiCorp Vault credentials configuration
Rootly validates the credentials by attempting an AppRole login against your Vault instance before saving. If the login fails, you’ll see: “cannot access Vault service. Please check your credentials.”

Integration connected

Your HashiCorp Vault integration is active. You can now define named secrets under Account > Secrets and reference them in any workflow action.

​
Defining Secrets

Once the Vault integration is connected, you create named secret references in Rootly that point to specific paths in your Vault KV store. These references are what you use in Liquid templates — Rootly fetches the actual secret value from Vault at workflow runtime.
By default, only Rootly owners and admins can create and manage secret definitions. You can adjust this via Rootly’s RBAC settings.
Navigate to Account > Secrets and define a new HashiCorp Vault secret:
Defining a HashiCorp Vault secret in Rootly
FieldDescription
NameA unique name for this secret reference in Rootly (e.g., pagerduty_key). This is the name you use in Liquid templates.
MountThe KV v2 mount path in Vault (default: secret).
PathThe path to the secret within the mount (e.g., integrations/pagerduty).
VersionThe KV v2 version number to read. Set to 0 to always read the latest version.

​
Using Secrets in Workflows

Once a secret is defined, you can reference it in any workflow action that supports Liquid templating using the following syntax: 
{{ secrets.SECRET_NAME.KEY_NAME }}
Where SECRET_NAME is the name you gave the secret in Rootly, and KEY_NAME is the key within the Vault secret JSON. For example, given a Vault secret at integrations/pagerduty containing: 
{
  "api_key": "pd_key_abc123",
  "webhook_token": {
    "value": "wh_secret_xyz789"
  }
}
You can reference it in a workflow action as: 
{{ secrets.pagerduty_key.api_key }}
{{ secrets.pagerduty_key.webhook_token.value }}
Nested secret keys are supported — use dot notation to traverse the JSON structure.

​
Troubleshooting

Rootly validates credentials by attempting an AppRole login at {instance_url}/v1/auth/AppRole/login. Confirm that:
  • The instance URL is reachable from Rootly’s servers (check any firewall or allowlist rules)
  • The namespace is correct — for HCP Vault, this is typically admin
  • The role_id and secret_id are both valid and haven’t expired or been rotated
  • The AppRole auth method is enabled at the path auth/AppRole in Vault
Check that:
  • The mount and path in the Rootly secret definition match the actual path in Vault
  • The version is set to 0 (latest) or a specific version that exists
  • The AppRole has a policy granting read access to the secret path in KV v2 format: secret/data/your/path
  • The KV engine is version 2 — KV v1 paths have a different structure and are not supported
Rootly uses dot notation to traverse JSON secret values. Ensure the key path in your Liquid template matches the JSON structure exactly, including case. For example, {{ secrets.my_secret.nested.foo }} requires a JSON structure of {"nested": {"foo": "value"}}.
The AppRole’s attached Vault policy must explicitly grant read capability on the KV v2 data path. KV v2 paths follow the pattern secret/data/<path> (not secret/<path>). A minimal policy granting read access looks like:
path "secret/data/integrations/*" {
  capabilities = ["read"]
}
Secret definitions are restricted to Rootly owners and admins by default. If you have a lower permission level, ask an admin to create the secret reference for you, or ask an admin to adjust the RBAC settings to allow your role to manage secrets.

​
Uninstall

To disconnect the integration, navigate to the integrations panel, open the Vault integration, and click Configure > Delete.

Incident Workflows

Use Vault secrets in workflow actions to authenticate with external systems during incidents.

Liquid Variables

Reference for all Liquid variables available in workflow actions alongside secrets.

Terraform

Manage Rootly resources as infrastructure as code with the Rootly Terraform provider.