> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superblocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# HashiCorp Vault

export const Alert = ({type, title, children}) => {
  const variant = ["info", "success", "warning", "danger", "note"].includes(type) ? type : "note";
  return <div className={`alert alert--${variant}`}>
      <div className="alert-icon" />
      <div className="alert-content">
        {title && <div className="alert-title">{title}</div>}
        <div className="alert-body">{children}</div>
      </div>
    </div>;
};

<Alert type="note">
  <p>
    <strong>Who can use this feature?</strong><br />
    Organization <strong>Owners</strong>, <strong>Admins</strong>, and other users with the <a href="/admin/org-administration/org-roles/permissions"><code>secrets:manage</code></a> permission
  </p>
</Alert>

Connect to your HashiCorp Vault to securely access application secrets, API keys, and sensitive data from your Superblocks integrations. This guide covers:

* How to [**set up a new secret store**](#set-up) connected to HashiCorp Vault
* Configuring and managing [**caching**](#caching) for your secret store to improve API performance
* [**Using secrets**](#using-secrets) throughout the Superblocks platform

### Prerequisites

To set up HashiCorp Vault as a secret store for Superblocks you'll need:

* An on-premises deployment of HashiCorp OR a HashiCorp account with [**Vault**](https://www.vaultproject.io/) configured
* Permission to manage HashiCorp Services, access to manage HashiCorp Vault cluster, and ability to create and configure Secrets engines

## Set up

### Create Secrets Engine with secrets key-value pair

To set up a key-value secrets engine in HashiCorp Vault:

1. Navigate to your **Vault** Cluster
2. Launch the Vault **Web UI**
3. In the Vault Web UI, navigate to **Secrets Engine**
4. Proceed to create a new secrets engine
5. Choose KV Version. Opt for either version 1 or 2 of the Key-Value (KV) secrets engine, based on your requirements
6. Add your secrets as key-value pairs
7. Customize the path and configure access to your secrets as needed

### Configure secret store

Finally, configure a new secret store in Superblocks:

1. Go to the [**Secrets Management**](https://app.superblocks.com/secrets-management) page in Superblocks
2. Click the **HashiCorp Vault** tile
3. Name your secret store
4. Paste or enter in the info for Address, Namespace, Path, Version, Auth Type, and Token configurations that were set in your Secrets engine

<table>
  <tr>
    <th>Address</th>

    <td>
      The Address is your cluster's public URL. It is located on the <strong>Vault</strong> Cluster page when you select your <strong>Vault</strong>.
    </td>
  </tr>

  <tr>
    <th>Namespace</th>

    <td>
      The <a href="https://developer.hashicorp.com/vault/docs/enterprise/namespaces">Namespace</a> is used for creating service accounts and managing who can access what. The default value is <code>admin</code>. It is optional and configured on the secrets engine.
    </td>
  </tr>

  <tr>
    <th>Path</th>

    <td>
      The Path tells <strong>Vault</strong> which secrets engine it should route requests to. It is configured in the Key Value secrets engine.
    </td>
  </tr>

  <tr>
    <th>Version</th>

    <td>
      The Version is which version of Key Value secrets engine to use (either v1 or v2 currently). It is configured in the Key Value secrets engine.
    </td>
  </tr>

  <tr>
    <th>Auth Type</th>

    <td>
      The Auth Type specifies which Auth flavor to use for connecting to HashiCorp Vault. The default configuration is Token. App Role is also available which requires a <code>Role ID</code> and <code>Secrets ID</code>.
    </td>
  </tr>

  <tr>
    <th>Token</th>

    <td>
      The Token is used to authenticate requests for secrets. It is located on the <strong>Vault</strong> Cluster page when you select your <strong>Vault</strong>.
    </td>
  </tr>
</table>

1. Configure caching rules for this store
2. Optionally, add more configurations for [different environments](/development-lifecycle/build/data-tags)
3. Click **Create**

<Alert type="success">
  Your secret store is now configured. Developers can now <a href="/development-lifecycle/build/using-secrets">reference secrets</a> in their integration forms.
</Alert>

## Caching

If enabled, Superblocks can cache your secrets, reducing calls to your secrets manager and improving API performance when using secrets. Caching can be configured for each of your secret store's configurations, letting you set different policies based on the environment.

To configure caches, go to [**Secrets Management**](https://app.superblocks.com/secrets-management) and click into your secrets store. From here you can:

* Update the **Cache TTL (seconds)** to your desired caching interval
* **Clear the cache** if you've rotated a secrets and need Superblocks to refetch secret values

![Manage secret caching](https://superblocks-demo.s3.us-west-2.amazonaws.com/secrets-caching.png "Manage secret caching")

<Alert type="info">
  If you're self-hosting with Hybrid or Cloud-Prem architectures, secrets are cached in-memory by the data plane. For scaled deployments, you'll need to clear each instance's cache individually when rotating secrets. To rotate secrets more easily, disable caching first. Then, after updating the secret, re-enable caching.
</Alert>

## Auth token renewal

When using the **token** auth type for accessing the configured secret store, if the configured token is renewable, it will be renewed every time the secret store is accessed.

For the token to be renewed it must:

* Be renewable (i.e. the "renewable" attribute is true)
* Have permissions to renew itself
* Not be expired

If the preceding conditions are met, the token will be renewed to the TTL that was set when the token was initially created (e.g. if the token was created with a TTL of 1 hour, each renewal will reset the TTL to 1 hour). The token will be renewed every time the secret store is accessed, for example when an API runs a step that uses an integration referencing the secret store.

<Alert type="info">
  Note: If the access token has a max TTL set on it, the renewed TTL will be capped so that the token's total lifetime never exceeds the max TTL.

  <br />

  <br />

  E.g. Given a token with an initial TTL of 4 minutes and a max TTL of 5 minutes, if the token is renewed after 3 minutes (1 minute remaining), the TTL will be reset to 2 minutes (not 4 minutes)
</Alert>

## Using secrets

For details on how to reference secrets in integration forms, see [Using secrets](/development-lifecycle/build/using-secrets).