> ## 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.

# Secrets Management

> Store and manage cloud provider credentials for your storage locations — directly or through an external vault.

Secrets store the cloud provider credentials that DataRaven uses to access your storage locations. Every location references a secret, and DataRaven supports two storage modes to fit your security requirements.

<CardGroup cols={2}>
  <Card icon="shield-halved" title="Native Vault">
    Enter credentials directly. Stored encrypted in **AWS SSM Parameter Store** (SecureString). Simple, secure, zero configuration.
  </Card>

  <Card icon="vault" title="External Vault (BYOV)">
    Map credential fields to references in **1Password**, **Doppler**, or **Infisical**. Credentials resolved at execution time and immediately discarded.
  </Card>
</CardGroup>

## Supported Providers

Each cloud storage provider requires specific credential fields. DataRaven auto-selects the auth method when you choose a provider — except Azure, which offers two options.

| Provider                  | Auth Method                           | Required Fields                         |
| ------------------------- | ------------------------------------- | --------------------------------------- |
| **AWS S3**                | `s3_access_key`                       | `access_key_id`, `secret_access_key`    |
| **Azure Blob**            | `azure_sas_url`                       | `sas_url`                               |
| **Azure Blob**            | `azure_account_key`                   | `account_name`, `account_key`           |
| **Google Cloud Storage**  | `gcs_service_account`                 | `service_account_json`                  |
| **Cloudflare R2**         | `r2_access_key`                       | `access_key_id`, `secret_access_key`    |
| **Backblaze B2**          | `b2_application_key`                  | `application_key_id`, `application_key` |
| **Wasabi**                | `wasabi_access_key`                   | `access_key_id`, `secret_access_key`    |
| **Railway**               | `railway_access_key`                  | `access_key_id`, `secret_access_key`    |
| **Oracle Object Storage** | `oracle_object_storage_s3_access_key` | `access_key_id`, `secret_access_key`    |
| **Tigris**                | `tigris_access_key`                   | `access_key_id`, `secret_access_key`    |
| **DigitalOcean Spaces**   | `digitalocean_spaces_access_key`      | `access_key_id`, `secret_access_key`    |
| **Hetzner**               | `hetzner_access_key`                  | `access_key_id`, `secret_access_key`    |
| **Rabata**                | `rabata_access_key`                   | `access_key_id`, `secret_access_key`    |
| **S3 Compatible**         | `s3_compatible_access_key`            | `access_key_id`, `secret_access_key`    |

## Creating a Secret

<Tabs>
  <Tab title="Direct Entry (Native Vault)">
    Store credentials directly in DataRaven's encrypted vault. Best for teams that don't use an external secrets manager.

    <Steps>
      <Step title="Choose your provider">
        Select the cloud storage provider. The auth method is auto-selected (Azure lets you choose between SAS URL and account key).
      </Step>

      <Step title="Enter credentials">
        Fill in the required credential fields for your provider. These are encrypted and stored in AWS SSM Parameter Store.
      </Step>

      <Step title="Name and save">
        Give the secret a descriptive name (e.g., "Production AWS" or "Staging GCS") and save.
      </Step>
    </Steps>
  </Tab>

  <Tab title="External Vault (BYOV)">
    Map credential fields to references in your external vault. Requires a [vault connection](/vault-integration) to be configured first.

    <Steps>
      <Step title="Select a vault connection">
        Choose an existing vault connection (1Password, Doppler, or Infisical). If you haven't created one yet, see the [Vault Integration guide](/vault-integration).
      </Step>

      <Step title="Map credential fields">
        For each required field, provide a reference to the corresponding secret in your vault.
      </Step>

      <Step title="Name and save">
        Give the secret a descriptive name and save. DataRaven validates that all required fields are mapped.
      </Step>
    </Steps>

    **Reference formats by provider:**

    | Vault Provider | Format                               | Example                              |
    | -------------- | ------------------------------------ | ------------------------------------ |
    | 1Password      | `op://VaultName/ItemName/field_name` | `op://DevOps/AWS-Prod/access_key_id` |
    | Doppler        | `SECRET_NAME`                        | `AWS_ACCESS_KEY_ID`                  |
    | Infisical      | `SECRET_NAME`                        | `AWS_ACCESS_KEY_ID`                  |
  </Tab>
</Tabs>

<Warning>
  You cannot provide both `credentials` and `vault_connection_id` on the same secret. Choose one storage mode — native vault or external vault — per secret.
</Warning>

## Validation Rules

DataRaven validates secrets on creation and update:

* **`auth_method`** must be valid for the chosen `secret_type`
* **`field_mappings`** must cover **all** required fields for the auth method (partial mappings are rejected)
* **`credentials`** and **`vault_connection_id`** are mutually exclusive

## Updating & Rotating Secrets

<Tabs>
  <Tab title="Native Vault">
    Edit a secret to rotate the credentials
  </Tab>

  <Tab title="External Vault (BYOV)">
    You have two options:

    1. **Update references** — Edit the secret resource with updated `field_mappings` if your vault paths changed
    2. **Update in your vault directly** — if the secret values changed but the references are the same, just update the values in 1Password/Doppler/Infisical. DataRaven resolves them at runtime, so changes take effect immediately.
  </Tab>
</Tabs>

<Note>
  You cannot switch a secret between native vault and external vault after creation. A native secret always uses `credentials`, and a BYOV secret always uses `field_mappings`.
</Note>

<Note>
  Changing `secret_type` on an existing secret triggers validation against all linked locations to ensure compatibility.
</Note>

## Secret Lifecycle

Secrets are referenced by **Locations**, which are referenced by **Tasks**. This creates a dependency chain:

<Steps>
  <Step title="Create a secret">
    Store credentials for a cloud provider using either storage mode.
  </Step>

  <Step title="Link to a location">
    When creating a storage location, select the secret that holds credentials for that provider.
  </Step>

  <Step title="Use in tasks">
    Tasks reference locations. At execution time, DataRaven resolves the secret's credentials to access the storage.
  </Step>

  <Step title="Deletion protection">
    A secret **cannot be deleted** while it's in use by one or more locations. You'll receive a `409 Conflict` error. Unlink or delete the dependent locations first.
  </Step>
</Steps>

The secret detail view shows all linked locations and tasks, along with creation metadata.

## Security

<CardGroup cols={2}>
  <Card icon="eye-slash" title="Never exposed">
    Credentials are **never returned** in any API response — not on read, not on list, not on update confirmation.
  </Card>

  <Card icon="lock" title="Encrypted at rest">
    Native vault credentials are stored as **AWS SSM Parameter Store SecureString** parameters, encrypted with AWS KMS.
  </Card>

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

  <Card icon="clipboard-list" title="Audit logged">
    All secret operations — creation, updates, deletions, and runtime resolutions — are logged for audit purposes.
  </Card>
</CardGroup>

## Provider Tips

<Accordion title="Azure Blob Storage">
  **Use SAS URLs over account keys.** SAS (Shared Access Signature) URLs are scoped to specific containers and operations, and they expire automatically. Account keys grant full access to the entire storage account.

  When using `azure_sas_url`, generate the SAS URL from the Azure portal with the minimum required permissions (read/write/list) and a reasonable expiration window.
</Accordion>

<Accordion title="Google Cloud Storage">
  The `service_account_json` field expects the **entire JSON key file** contents as a string. Copy the full JSON output from `gcloud iam service-accounts keys create` — don't extract individual fields.
</Accordion>

<Accordion title="Cloudflare R2">
  R2 credentials (`access_key_id` and `secret_access_key`) go in the secret. The **account ID** belongs in the Location's `endpoint_url` field, not in the secret — typically formatted as `https://<account_id>.r2.cloudflarestorage.com`.
</Accordion>

<Accordion title="Wasabi">
  Wasabi requires an `endpoint_url` in the **Location** configuration (e.g., `https://s3.us-east-1.wasabisys.com`). The secret only holds the access key credentials.
</Accordion>

<Accordion title="Tigris">
  Tigris uses standard S3 access key credentials. The `endpoint_url` goes in the **Location** configuration — typically `https://fly.storage.tigris.dev`.
</Accordion>

<Accordion title="DigitalOcean Spaces">
  DigitalOcean Spaces uses standard S3 access key credentials. The `endpoint_url` goes in the **Location** configuration — formatted as `<region>.digitaloceanspaces.com` (e.g., `nyc3.digitaloceanspaces.com`).
</Accordion>

<Accordion title="Hetzner">
  Hetzner Object Storage uses standard S3 access key credentials. The `endpoint_url` goes in the **Location** configuration — formatted as `<region>.your-objectstorage.com` (e.g., `hel1.your-objectstorage.com`).
</Accordion>

<Accordion title="Rabata">
  Rabata Object Storage uses standard S3 access key credentials. The `endpoint_url` goes in the **Location** configuration — formatted as `s3.<region>.rabata.io` (e.g., `s3.us-east-1.rabata.io`). Region is also required.
</Accordion>

## Tier Limits

| Plan     | Secrets |
| -------- | ------- |
| **Free** | 5       |
| **Pro**  | 100     |

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