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

# Create Vault Integration

> Register a HashiCorp Vault / OpenBao integration that later credential records can read secrets from.

## Overview

Registers an external secret-manager integration. v1 supports HashiCorp Vault (OSS, Enterprise, and OpenBao) via AppRole authentication. ScrapEngine never stores the raw username/password — instead, you point credentials at this integration and a vault path, and the authenticate task action reads the secret on demand using the registered AppRole. The `secret_id` is stored encrypted at rest.

## Body

<ParamField body="name" type="string" required={true}>
  Human-readable name. 1-100 characters.
</ParamField>

<ParamField body="type" type="string" required={true}>
  Backend type. Must be `hashicorp` (only value supported in v1).
</ParamField>

<ParamField body="config" type="object" required={true}>
  HashiCorp-specific configuration.

  <Expandable title="config properties">
    <ParamField body="config.address" type="string" required={true}>
      Vault address, for example `https://vault:8200`. Must include the protocol.
    </ParamField>

    <ParamField body="config.namespace" type="string">
      Optional Vault Enterprise namespace.
    </ParamField>

    <ParamField body="config.authMethod" type="string" required={true}>
      Auth method. Must be `approle` (only value supported in v1).
    </ParamField>

    <ParamField body="config.roleId" type="string" required={true}>
      AppRole `role_id`.
    </ParamField>

    <ParamField body="config.secretId" type="string" required={true}>
      AppRole `secret_id`. Stored encrypted at rest.
    </ParamField>
  </Expandable>
</ParamField>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.scrapengine.io/api/v1/vault-integrations" \
    -H "Authorization: Bearer $SCRAPENGINE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "prod-vault",
      "type": "hashicorp",
      "config": {
        "address": "https://vault.prod.example.com:8200",
        "namespace": "admin/scrapengine",
        "authMethod": "approle",
        "roleId": "8f2e1c0c-0e4a-4b58-8b2e-4a9e1c8a4a11",
        "secretId": "s.xxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.scrapengine.io/api/v1/vault-integrations",
    {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${process.env.SCRAPENGINE_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "prod-vault",
        type: "hashicorp",
        config: {
          address: "https://vault.prod.example.com:8200",
          authMethod: "approle",
          roleId: process.env.VAULT_ROLE_ID,
          secretId: process.env.VAULT_SECRET_ID,
        },
      }),
    },
  );
  const data = await response.json();
  ```
</CodeGroup>

## Response

### Success Response (201)

<ResponseField name="id" type="string">
  Integration ID (UUID). Reference from credential records.
</ResponseField>

<ResponseField name="name" type="string">
  The name you provided.
</ResponseField>

<ResponseField name="type" type="string">
  Always `hashicorp` in v1.
</ResponseField>

<ResponseField name="address" type="string">
  Vault address.
</ResponseField>

<ResponseField name="namespace" type="string">
  Vault Enterprise namespace, or `null` if unset.
</ResponseField>

<ResponseField name="authMethod" type="string">
  Always `approle` in v1.
</ResponseField>

<ResponseField name="roleId" type="string">
  AppRole role\_id (echoed back; `secret_id` is never returned).
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  ISO 8601 timestamp.
</ResponseField>

**Example Response:**

```json theme={null}
{
  "id": "5f8c6a74-5f2e-4f5a-9e58-5b9c3c7d2a11",
  "name": "prod-vault",
  "type": "hashicorp",
  "address": "https://vault.prod.example.com:8200",
  "namespace": "admin/scrapengine",
  "authMethod": "approle",
  "roleId": "8f2e1c0c-0e4a-4b58-8b2e-4a9e1c8a4a11",
  "createdAt": "2026-04-24T09:12:44Z",
  "updatedAt": "2026-04-24T09:12:44Z"
}
```

### Error Responses

| Status | Description                                                                            |
| ------ | -------------------------------------------------------------------------------------- |
| `400`  | Invalid body — missing required fields, bad URL, or unsupported `type` / `authMethod`. |
| `401`  | Unauthorized — invalid or missing API key.                                             |