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

# Secrets

> Store and manage sensitive data with HashiCorp Vault

Vault Secrets provides secure storage for sensitive data like API keys, database credentials, and certificates. All secrets are encrypted at rest and support versioning for audit and rollback capabilities.

## Key Features

<CardGroup cols={2}>
  <Card title="Encrypted Storage" icon="lock">
    All secrets are encrypted at rest using Vault's seal mechanism. Data is never stored in plaintext.
  </Card>

  <Card title="Version History" icon="clock-rotate-left">
    Every change creates a new version. View, compare, and rollback to any previous version.
  </Card>

  <Card title="Folder Organization" icon="folder-tree">
    Organize secrets into folders (paths) for logical grouping by application, environment, or team.
  </Card>

  <Card title="Rotation Tracking" icon="rotate">
    Automatic age tracking with warnings when secrets should be rotated based on policy.
  </Card>
</CardGroup>

## Secret Rotation

Secrets are automatically tracked for age to encourage regular rotation. The system classifies secrets based on how long ago they were last updated:

| Status       | Age        | Meaning                            |
| ------------ | ---------- | ---------------------------------- |
| **OK**       | \< 30 days | Recently updated, no action needed |
| **Warning**  | 30-90 days | Consider rotating soon             |
| **Critical** | > 90 days  | Rotate immediately                 |

<Info>
  Rotation status is calculated from the secret's last update time. Any change to a secret (adding, modifying, or deleting keys) creates a new version and resets the age counter.
</Info>

## Required Permissions

| Action                | Permission                      |
| --------------------- | ------------------------------- |
| View/Read secrets     | `iam:project:cicd:vault:read`   |
| Create/Update secrets | `iam:project:cicd:vault:write`  |
| Delete secrets        | `iam:project:cicd:vault:delete` |

## Concepts

### Mounts

A mount is a logical grouping of secrets, similar to a filesystem mount point. Common mounts include:

* `secret/` - General purpose key-value secrets
* `database/` - Database credentials
* `kv/` - Key-value store

### Paths

Paths organize secrets within a mount. Use slashes to create folder hierarchies:

```
secret/
├── app/
│   ├── database      # secret at secret/app/database
│   └── api-keys      # secret at secret/app/api-keys
└── shared/
    └── certificates  # secret at secret/shared/certificates
```

### Keys

Each secret contains one or more key-value pairs. For example, a database secret might have:

* `username`: the database username
* `password`: the database password
* `host`: the database hostname

## How to Navigate Secrets

<Steps>
  <Step title="Select a Mount">
    From the Vault Secrets page, click on a mount to browse its contents.
  </Step>

  <Step title="Browse Folders">
    Click on folders to navigate deeper into the path hierarchy. The breadcrumb shows your current location.
  </Step>

  <Step title="View a Secret">
    Click on a secret (key icon) to open the detail page and view its key-value pairs.
  </Step>

  <Step title="Go Back">
    Use the back button or breadcrumb to navigate up the folder hierarchy.
  </Step>
</Steps>

## How to Create a Secret

<Steps>
  <Step title="Navigate to Target Folder">
    Browse to the folder where you want to create the secret.
  </Step>

  <Step title="Click New Secret">
    Click the **New Secret** button in the top right.
  </Step>

  <Step title="Enter Secret Path">
    Provide a name for the secret. Use slashes to create subfolders:

    * `database` - Creates secret at current path
    * `app/config` - Creates `app` folder and `config` secret inside
  </Step>

  <Step title="Add Key-Value Pairs">
    Add one or more key-value pairs:

    * Enter a key name (e.g., `password`)
    * Enter the value (hidden by default)
    * Toggle **JSON** for complex data structures
  </Step>

  <Step title="Create">
    Click **Create Secret**. The secret is encrypted and stored.
  </Step>
</Steps>

<Info>
  Secret paths can only contain alphanumeric characters, hyphens, underscores, and slashes. They cannot start or end with a slash.
</Info>

## How to View and Edit a Secret

<Steps>
  <Step title="Open the Secret">
    Navigate to and click on the secret to open its detail page.
  </Step>

  <Step title="Reveal Values">
    Click the eye icon on any row to reveal the hidden value.
  </Step>

  <Step title="Edit Values">
    Modify the key names or values directly in the input fields.
  </Step>

  <Step title="Save Changes">
    Click **Save Changes** to create a new version with your modifications.
  </Step>
</Steps>

### Row View vs JSON View

Toggle between two editing modes:

| Mode          | Best For               | Features                                            |
| ------------- | ---------------------- | --------------------------------------------------- |
| **Row View**  | Simple key-value pairs | Individual field editing, show/hide per value       |
| **JSON View** | Complex structures     | Full Monaco editor, syntax highlighting, paste JSON |

Click the braces icon (`{}`) to switch to JSON view. Click the list icon to return to row view.

## How to Add a New Key

<Steps>
  <Step title="Open the Secret">
    Navigate to the secret detail page.
  </Step>

  <Step title="Click Add Key">
    Click the **Add Key** button.
  </Step>

  <Step title="Enter Details">
    A new row appears at the top:

    * Enter the key name
    * Enter the value
    * Toggle JSON if needed
  </Step>

  <Step title="Save">
    Click **Save Changes** to persist the new key.
  </Step>
</Steps>

<Tip>
  New keys are marked with an "Unsaved" badge until you save. You can add multiple keys before saving.
</Tip>

## How to Delete a Key

<Steps>
  <Step title="Find the Key">
    Locate the key you want to delete in the secret detail page.
  </Step>

  <Step title="Click Delete">
    Click the trash icon on the key's row.
  </Step>

  <Step title="Confirm">
    Confirm the deletion. The key is removed from the secret.
  </Step>
</Steps>

<Warning>
  Deleting a key creates a new version without that key. The key still exists in previous versions and can be recovered via rollback.
</Warning>

## How to Delete a Secret

<Steps>
  <Step title="Navigate to the Folder">
    Go to the folder containing the secret.
  </Step>

  <Step title="Click Delete">
    Click the trash icon on the secret's row.
  </Step>

  <Step title="Confirm">
    Confirm the deletion. The entire secret and all its keys are removed.
  </Step>
</Steps>

## How to Copy Values

* **Single Value**: Click the copy icon on any row to copy that value
* **All Values**: Click the clipboard icon in the toolbar to copy the entire secret as JSON

Copied values can be pasted into applications, configuration files, or other secrets.

## Version History

Every change to a secret creates a new version. Access version history to:

* View previous values
* Compare versions side-by-side
* Rollback to a previous state
* Destroy old versions permanently

### How to View Version History

<Steps>
  <Step title="Open the Secret">
    Navigate to the secret detail page.
  </Step>

  <Step title="Click History">
    Click the clock/history icon in the toolbar.
  </Step>

  <Step title="Browse Versions">
    The left panel shows all versions with status:

    * **Current**: Active version
    * **Available**: Can be viewed or rolled back
    * **Deleted**: Soft-deleted, can be restored
    * **Destroyed**: Permanently removed
  </Step>

  <Step title="Preview Version">
    Click a version to preview its contents in the right panel.
  </Step>
</Steps>

### How to Compare Versions

<Steps>
  <Step title="Select Base Version">
    Click on a version in the history list.
  </Step>

  <Step title="Click Compare">
    Click the **Compare** button that appears.
  </Step>

  <Step title="View Diff">
    The preview panel shows both versions side-by-side for comparison.
  </Step>
</Steps>

### How to Rollback to a Previous Version

<Steps>
  <Step title="Select the Version">
    Click on the version you want to restore.
  </Step>

  <Step title="Click Rollback">
    Click the **Rollback** button.
  </Step>

  <Step title="Confirm">
    A new version is created with the old data. The current version is preserved in history.
  </Step>
</Steps>

<Info>
  Rollback creates a new version rather than overwriting. This preserves the complete audit trail.
</Info>

### How to Destroy a Version

<Steps>
  <Step title="Select the Version">
    Click on the version you want to permanently remove.
  </Step>

  <Step title="Click Destroy">
    Click the trash icon on the version.
  </Step>

  <Step title="Confirm">
    The version is permanently destroyed and cannot be recovered.
  </Step>
</Steps>

<Warning>
  Destroy is irreversible. Use this only for compliance requirements or to remove accidentally stored sensitive data.
</Warning>

## Working with JSON Values

For complex data structures, enable JSON mode on individual keys:

<Steps>
  <Step title="Toggle JSON Mode">
    Enable the **JSON** switch on the key's row.
  </Step>

  <Step title="Edit JSON">
    A code editor appears with syntax highlighting:

    ```json theme={null}
    {
      "nested": {
        "key": "value"
      },
      "array": [1, 2, 3]
    }
    ```
  </Step>

  <Step title="Validate">
    Invalid JSON shows an error. Fix syntax before saving.
  </Step>
</Steps>

<Tip>
  Use JSON mode for storing configuration objects, arrays, or any structured data that needs to maintain its format.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Cannot see secrets" icon="circle-question">
    * Verify you have read permission for Vault
    * Check that the mount exists and is accessible
    * Ensure you're in the correct project context
  </Accordion>

  <Accordion title="Cannot create or edit secrets" icon="circle-question">
    * You need write permission for Vault
    * The secret path may already exist (use a different name)
    * Check for invalid characters in the path
  </Accordion>

  <Accordion title="JSON validation error" icon="circle-question">
    * Check for missing commas between key-value pairs
    * Ensure strings are wrapped in double quotes
    * Validate brackets and braces match
    * Use a JSON validator to find syntax errors
  </Accordion>

  <Accordion title="Version history empty" icon="circle-question">
    * New secrets have only one version initially
    * Make and save changes to create new versions
    * Destroyed versions don't appear in history
  </Accordion>

  <Accordion title="Cannot rollback" icon="circle-question">
    * You need write permission to rollback
    * Destroyed versions cannot be rolled back
    * The target version may be corrupted
  </Accordion>

  <Accordion title="Secret age showing critical" icon="circle-question">
    * This is a policy reminder, not an error
    * Rotate the secret by updating its values
    * Any change creates a new version and resets the age
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="How are secrets encrypted?">
    Secrets are encrypted using Vault's seal mechanism with AES-256-GCM. The encryption key is protected by the unseal keys and never stored in plaintext.
  </Accordion>

  <Accordion title="Who can access my secrets?">
    Access is controlled by Vault policies. Only users with appropriate permissions can read, write, or delete secrets in specific paths.
  </Accordion>

  <Accordion title="Can I recover a deleted secret?">
    Soft-deleted secrets can be recovered if not yet destroyed. Destroyed secrets are permanently removed and cannot be recovered.
  </Accordion>

  <Accordion title="How long is version history kept?">
    Version history is kept indefinitely unless explicitly destroyed. Storage policies may vary by installation.
  </Accordion>

  <Accordion title="Can I reference secrets in pipelines?">
    Yes. Secrets can be injected into pipeline environments using the Vault integration. See pipeline documentation for details.
  </Accordion>

  <Accordion title="What's the difference between delete and destroy?">
    Delete removes the current version but keeps it recoverable. Destroy permanently removes the data with no recovery possible.
  </Accordion>
</AccordionGroup>