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

# Vault Integration

> Connect your secrets manager to DataRaven for zero-knowledge credential management with BYOV (Bring Your Own Vault).

DataRaven's **Bring Your Own Vault (BYOV)** architecture ensures your cloud credentials never touch
our infrastructure. Connect your existing secrets manager, map fields to vault references, and
DataRaven resolves credentials in-memory at transfer time — then immediately discards them.

<Note>
  BYOV is optional. DataRaven also provides **built-in secret storage** powered by AWS SSM Parameter
  Store SecureString. You can store credentials securely without connecting an external vault.
</Note>

<Warning>
  **Self-hosted vaults are not supported** at this time. Only managed/cloud-hosted instances of
  1Password, Doppler, and Infisical are supported.
</Warning>

## How It Works

<Steps>
  <Step title="Connect your vault">
    Go to **Settings → Vault Connections → Add Connection**, select your provider, and provide a
    scoped access token. DataRaven encrypts the token and stores it in AWS SSM Parameter Store —
    it's never returned in API responses.
  </Step>

  <Step title="Create secrets with field mappings">
    Create a secret that maps DataRaven field names (like `access_key_id`) to references in your
    vault (like `op://DevOps/AWS-Prod/access_key_id`). Each mapping tells DataRaven where to find
    the credential at runtime.
  </Step>

  <Step title="Reference secrets in locations">
    When configuring a storage location, select your vault-backed secret instead of entering
    credentials directly. The location will resolve credentials from your vault every time it's
    used.
  </Step>

  <Step title="Zero-knowledge resolution">
    At execution time, DataRaven authenticates to your vault, resolves the mapped credentials into
    memory, performs the transfer operation, and immediately discards them. Nothing is cached or
    persisted.
  </Step>
</Steps>

## Supported Providers

<Tabs>
  <Tab title="1Password">
    ### Authentication

    1Password connections use a **Service Account Token** (starts with `ops_`).

    | Field          | Required | Description                       |
    | -------------- | -------- | --------------------------------- |
    | `access_token` | ✅        | Service account token (`ops_...`) |

    ### Setup

    1. Open **1Password** → **Settings** → **Developer** → **Service Accounts**
    2. Click **New Service Account**
    3. Give it a descriptive name (e.g., "DataRaven Production")
    4. Grant **read access** to the vaults containing your cloud credentials
    5. Copy the generated token — it's only shown once

    No additional configuration is needed beyond the token.

    ### Field Mapping Format

    1Password uses the `op://` URI format to reference individual fields:

    ```
    op://vault-name/item-name/field-name
    ```

    **Example — S3 credentials:**

    ```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
    {
      "field_mappings": [
        {"field_name": "access_key_id", "reference": "op://DevOps/AWS-Prod/access_key_id"},
        {"field_name": "secret_access_key", "reference": "op://DevOps/AWS-Prod/secret_access_key"}
      ]
    }
    ```

    <Tip>
      Use descriptive vault and item names in 1Password so your `op://` references are self-documenting.
    </Tip>
  </Tab>

  <Tab title="Doppler">
    ### Authentication

    Doppler connections use a **Service Token** (starts with `dp.st.`) scoped to a specific project and config.

    | Field          | Required | Description                                 |
    | -------------- | -------- | ------------------------------------------- |
    | `access_token` | ✅        | Service token (`dp.st....`)                 |
    | `project`      | ✅        | Doppler project slug                        |
    | `config`       | ✅        | Config name (e.g., `production`, `staging`) |

    ### Setup

    1. Open **Doppler** → select your **Project**
    2. Go to **Access** → **Generate Service Token**
    3. Select the **config** (environment) to scope the token to
    4. Copy the generated token

    <Note>
      Doppler tokens are scoped to a single project + config combination. If you need credentials from multiple projects, create separate vault connections.
    </Note>

    ### Field Mapping Format

    Doppler uses the secret name directly — no path syntax needed:

    ```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
    {
      "field_mappings": [
        {"field_name": "access_key_id", "reference": "AWS_ACCESS_KEY_ID"},
        {"field_name": "secret_access_key", "reference": "AWS_SECRET_ACCESS_KEY"}
      ]
    }
    ```
  </Tab>

  <Tab title="Infisical">
    ### Authentication

    Infisical connections use **Universal Auth** via a Machine Identity, requiring a client ID and client secret pair.

    | Field           | Required | Description                                 |
    | --------------- | -------- | ------------------------------------------- |
    | `client_id`     | ✅        | UUID from Machine Identity                  |
    | `client_secret` | ✅        | Secret from Machine Identity                |
    | `project_id`    | ✅        | Infisical project ID (UUID)                 |
    | `environment`   | ✅        | Environment slug (`dev`, `staging`, `prod`) |
    | `secret_path`   | ❌        | Path to secrets folder (defaults to `/`)    |

    ### Setup

    1. Open your Infisical project → **Project Settings** → **Access Control**
    2. Go to **Machine Identities** → **Create**
    3. Enable **Universal Auth** for the identity
    4. Generate a client ID and client secret
    5. Grant the identity read access to the project and environment containing your credentials
    6. Copy the **project ID** from **Project Settings → General**

    <Warning>
      Infisical does not support token rotation through the API. To rotate credentials, you must **delete the vault connection and create a new one** with updated Machine Identity credentials.
    </Warning>

    ### Field Mapping Format

    Infisical uses the secret name directly, similar to Doppler:

    ```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
    {
      "field_mappings": [
        {"field_name": "access_key_id", "reference": "AWS_ACCESS_KEY_ID"},
        {"field_name": "secret_access_key", "reference": "AWS_SECRET_ACCESS_KEY"}
      ]
    }
    ```
  </Tab>
</Tabs>

## Token Management

Once a vault connection is created, you can manage it from the connection detail page.

### Test Connection

Click **Test Connection** to verify that DataRaven can authenticate with your vault. A successful
test returns:

* **1Password:** Number of accessible vaults
* **Doppler / Infisical:** Number of accessible secrets

Testing also updates the **verification status** timestamp, so you can track when a connection was
last confirmed working.

### Rotate Token

<Tabs>
  <Tab title="1Password & Doppler">
    Click **Rotate Token** from the connection detail page. Enter the new token and DataRaven will replace the encrypted token in storage. All secrets using this connection will immediately use the new token — no other changes needed.
  </Tab>

  <Tab title="Infisical">
    Token rotation is not available for Infisical connections. To rotate credentials:

    1. Create a new Machine Identity in Infisical (or regenerate the client secret)
    2. Delete the existing vault connection in DataRaven
    3. Create a new vault connection with the updated credentials
    4. Re-link any secrets that referenced the old connection
  </Tab>
</Tabs>

## Security

<CardGroup cols={2}>
  <Card title="Encrypted at rest" icon="lock">
    Vault tokens are encrypted and stored in **AWS SSM Parameter Store** SecureString parameters.
    They are never stored in DataRaven's database.
  </Card>

  <Card title="Never exposed" icon="eye-slash">
    Tokens and credentials are **never returned in API responses**. The API only surfaces a vault
    reference ID.
  </Card>

  <Card title="In-memory only" icon="memory">
    Cloud credentials are resolved in-memory at execution time and **immediately discarded** after
    the operation completes.
  </Card>

  <Card title="Audit logged" icon="clipboard-list">
    All vault operations — connections, tests, rotations, and secret resolutions — are logged for
    audit purposes.
  </Card>
</CardGroup>

<Tip>
  Follow the principle of **minimum privilege** when creating vault tokens. Grant read-only access
  to only the specific vaults, projects, or environments that DataRaven needs.
</Tip>

## Tier Limits

| Plan     | Vault Connections |
| -------- | ----------------- |
| **Free** | 1                 |
| **Pro**  | 10                |

Need more? [Upgrade your plan](https://app.dataraven.io) from the billing page.