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

# Vault

> Store API keys, tokens, and secrets in the encrypted organization Vault and reference them securely from Ravenna workflows and integrations.

Vault provides encrypted credential storage at the organization level. Use it to securely store API keys, tokens, and other secrets that your <Tooltip headline="Workflows" tip="Automated sequences of actions triggered by events" cta="Learn about workflows" href="/documentation/automate/workflows/overview">workflows</Tooltip> and integrations can reference at runtime.

<View title="Human" icon="user">
  ***

  ## Get started

  <Steps>
    <Step title="Open organization settings">
      Click your organization name in the top left, then select **Settings** from the dropdown menu.
    </Step>

    <Step title="Select Vault">
      Click **Vault** in the left sidebar.
    </Step>
  </Steps>

  <Info>
    Vault requires the organization admin role. Organization members and guests cannot access or manage credentials.
  </Info>

  ***

  ## Manage credentials

  ### Create a credential

  <Steps>
    <Step title="Open the create form">
      Click **Add Credential** on the Vault page.
    </Step>

    <Step title="Enter credential details">
      Provide a **Name** to identify the credential and the secret **Value** (API key, token, or password).
    </Step>

    <Step title="Save the credential">
      Click **Save**. The value is encrypted immediately and cannot be viewed again after creation.
    </Step>
  </Steps>

  A hint showing the first and last few characters of the value is displayed to help you identify credentials later.

  <Info>
    Credential names must be unique within your organization.
  </Info>

  ### Edit a credential

  <Steps>
    <Step title="Find the credential">
      Navigate to **Settings > Vault** and locate the credential you want to update.
    </Step>

    <Step title="Open the edit form">
      Click the credential to open its details.
    </Step>

    <Step title="Update fields">
      Change the **Name** or enter a new **Value**. The previous value is never pre-filled for security reasons, so you must re-enter it if updating.
    </Step>

    <Step title="Save changes">
      Click **Save** to apply your changes.
    </Step>
  </Steps>

  ### Delete a credential

  <Steps>
    <Step title="Find the credential">
      Navigate to **Settings > Vault** and locate the credential you want to delete.
    </Step>

    <Step title="Delete the credential">
      Click the delete option and confirm the deletion.
    </Step>
  </Steps>

  <Warning>
    Deleting a credential may break workflows or integrations that reference it. Verify no active workflows use a credential before removing it.
  </Warning>

  ***

  ## Use credentials in workflows

  Vault credentials are available in the **HTTP Request** workflow action. When configuring authentication, select a credential from the dropdown to securely provide the secret value.

  Supported authentication methods:

  * **API Key** - Select a vault credential for the API key value
  * **Bearer Token** - Select a vault credential for the bearer token value
  * **Basic Auth** - Select a vault credential for the password field

  Credentials are decrypted only at runtime during workflow execution and are never exposed in the workflow builder or logs.

  <Callout icon="link" color="#6B7280">
    Learn more about the [HTTP Request action and other workflow actions](/documentation/automate/workflows/triggers-actions)
  </Callout>

  ***

  ## Security

  Vault credentials are protected with multiple layers of security:

  * **Encryption at rest** - Values are encrypted using AES-256-GCM envelope encryption
  * **Write-only storage** - Values are never returned by the API or displayed in the UI after creation
  * **Organization-scoped isolation** - Credentials are only accessible within the organization that created them
  * **Admin-only access** - Only organization admins can create, edit, or delete credentials
</View>

<View title="Agent" icon="bot">
  ## Overview

  | Property | Detail                                                                                 |
  | -------- | -------------------------------------------------------------------------------------- |
  | Scope    | Organization                                                                           |
  | Access   | Organization admin only                                                                |
  | Location | Settings > Vault                                                                       |
  | Purpose  | Encrypted storage for API keys, tokens, and secrets used by workflows and integrations |

  ***

  ## Credential model

  ### Properties

  | Field      | Description                                                                                      |
  | ---------- | ------------------------------------------------------------------------------------------------ |
  | Name       | Unique identifier within the organization. Used to select credentials in workflow configuration. |
  | Hint       | First and last few characters of the value, displayed for identification purposes.               |
  | Type       | The kind of credential stored (API key, token, password).                                        |
  | Created at | Timestamp when the credential was first created.                                                 |
  | Updated at | Timestamp of the most recent update to the credential.                                           |

  ### Operations

  | Operation   | Access level       | Notes                                                                      |
  | ----------- | ------------------ | -------------------------------------------------------------------------- |
  | Create      | Organization admin | Name must be unique per organization. Value is encrypted immediately.      |
  | Read (list) | Organization admin | Returns name, hint, and metadata only. Values are never returned.          |
  | Update      | Organization admin | Can change name or value. Value must be re-entered (never pre-filled).     |
  | Delete      | Organization admin | Permanent. May break workflows or integrations referencing the credential. |

  ### Constraints

  * Credential names must be unique within an organization.
  * Values cannot be viewed after creation. Only a character hint is available for identification.
  * Only organization admins can manage vault credentials.
  * Deleting a credential does not automatically update workflows or integrations that reference it. Verify usage before deletion.
  * Credentials are encrypted at rest using AES-256-GCM envelope encryption.

  ***

  ## Workflow integration

  Vault credentials are referenced in the HTTP Request workflow action through authentication configuration fields.

  **Supported authentication types:**

  | Auth type    | Vault-eligible field | Header format                                      |
  | ------------ | -------------------- | -------------------------------------------------- |
  | API Key      | API key value        | Configurable header name (default: `X-API-Key`)    |
  | Bearer Token | Token value          | `Authorization: Bearer <token>`                    |
  | Basic Auth   | Password             | `Authorization: Basic <base64(username:password)>` |

  Credentials are decrypted at runtime only during workflow execution. They are never exposed in the workflow builder, logs, or API responses.
</View>