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

# Push Secret to Vault

> Write a KV secret to your underlying vault via a registered integration. The raw values are forwarded to your vault and never stored by ScrapEngine.

## Overview

Writes a KV secret to the vault behind a registered integration. This is the only channel through which a raw username/password ever enters ScrapEngine — the payload is forwarded to your vault in the same request and not persisted on our side. For HashiCorp KV v2 (the default) the secret lands at `<mount>/data/<path>`; use this endpoint to seed the vault entries that your credential records reference.

## Path Parameters

<ParamField path="id" type="string" required={true}>
  Integration ID (UUID) of the vault to write to.
</ParamField>

## Body

<ParamField body="path" type="string" required={true}>
  Vault KV path without the mount or `/data/` prefix. 1-200 characters. For KV v2 mounted at `secret`, this is stored under `secret/data/<path>`.
</ParamField>

<ParamField body="mount" type="string" default="secret">
  KV mount point. Defaults to `secret`.
</ParamField>

<ParamField body="data" type="object" required={true}>
  Key/value pairs to store under the path. All values must be strings. This is the only channel in which the raw secret enters our system; it is forwarded to your vault and never stored by us.
</ParamField>

<ParamField body="metadata" type="object">
  Optional `custom_metadata` (KV v2) for free-form labels — name, description, owner, etc. All values must be strings.
</ParamField>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.scrapengine.io/api/v1/vault-integrations/5f8c6a74-5f2e-4f5a-9e58-5b9c3c7d2a11/secrets" \
    -H "Authorization: Bearer $SCRAPENGINE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "path": "login-alice",
      "mount": "secret",
      "data": {
        "username": "alice@example.com",
        "password": "hunter2"
      },
      "metadata": {
        "name": "Alice login",
        "description": "app.example.com invoices flow"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.scrapengine.io/api/v1/vault-integrations/5f8c6a74-5f2e-4f5a-9e58-5b9c3c7d2a11/secrets",
    {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${process.env.SCRAPENGINE_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        path: "login-alice",
        data: { username: "alice@example.com", password: "hunter2" },
      }),
    },
  );
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.scrapengine.io/api/v1/vault-integrations/5f8c6a74-5f2e-4f5a-9e58-5b9c3c7d2a11/secrets",
      headers={
          "Authorization": f"Bearer {SCRAPENGINE_API_KEY}",
          "Content-Type": "application/json",
      },
      json={
          "path": "login-alice",
          "data": {"username": "alice@example.com", "password": "hunter2"},
      },
  )
  data = response.json()
  ```
</CodeGroup>

## Response

### Success Response (201)

<ResponseField name="path" type="string">
  The path the secret was written to (as supplied).
</ResponseField>

<ResponseField name="mount" type="string">
  The mount point used — either what you supplied or the default (`secret`).
</ResponseField>

<ResponseField name="version" type="integer">
  KV v2 version assigned by vault. Omitted for backends that don't version secrets.
</ResponseField>

**Example Response:**

```json theme={null}
{
  "path": "login-alice",
  "mount": "secret",
  "version": 1
}
```

### Error Responses

| Status | Description                                                                                                        |
| ------ | ------------------------------------------------------------------------------------------------------------------ |
| `400`  | Invalid body — non-string value in `data` / `metadata`, path too long, or the underlying vault rejected the write. |
| `401`  | Unauthorized — invalid or missing API key.                                                                         |
| `404`  | Integration not found or not owned by the caller.                                                                  |