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

# Create a vault

> Register a secrets provider for your organization.

export const Notice = ({kind = "note", title, children}) => {
  const kinds = {
    warning: {
      label: "User notice",
      icon: <>
          <path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3" />
          <path d="M12 9v4" />
          <path d="M12 17h.01" />
        </>
    },
    gotcha: {
      label: "Gotcha",
      icon: <>
          <circle cx="12" cy="12" r="10" />
          <path d="M12 16v-4" />
          <path d="M12 8h.01" />
        </>
    },
    note: {
      label: "Note",
      icon: <>
          <circle cx="12" cy="12" r="10" />
          <path d="M12 16v-4" />
          <path d="M12 8h.01" />
        </>
    }
  };
  const k = kinds[kind];
  return <div className="notice my-6 rounded-xl border border-zinc-200 bg-white p-5 dark:border-zinc-800 dark:bg-zinc-950">
      <div className={`${kind === "warning" ? "not-prose flex items-center gap-1.5 text-xs font-semibold uppercase tracking-wide text-red-400/80 dark:text-red-400/70" : kind === "gotcha" ? "not-prose flex items-center gap-1.5 text-xs font-semibold uppercase tracking-wide text-amber-500/80 dark:text-amber-400/70" : "not-prose flex items-center gap-1.5 text-xs font-semibold uppercase tracking-wide text-zinc-400 dark:text-zinc-500"}`}>
        <svg className="h-3.5 w-3.5" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
          {k.icon}
        </svg>
        {k.label}
      </div>
      {title && <div className="not-prose mt-2 text-base font-semibold text-zinc-900 dark:text-zinc-100">{title}</div>}
      <div className="notice-body mt-3 text-sm leading-6 text-zinc-700 dark:text-zinc-300">{children}</div>
    </div>;
};

Registers a [vault](/agents-api/vaults/overview) (a link between your organization and an external secrets provider) so an agent can sign in to the sites it works on without you passing the secrets through the API. Today the only provider is [1Password](https://developer.1password.com/): you record which 1Password vault to read (`op_vault_id`) and a [service account token](https://www.1password.dev/service-accounts) that grants access to it.

The token is validated against the provider before it is stored, and is never returned by any endpoint.

Returns `201` with the created vault object (see [Retrieve](/agents-api/vaults/retrieve) for the full field list).

<Notice kind="warning" title="Plaintext token in the request body">
  The service account token travels in clear text inside the body. Send it only over HTTPS and never log the request.
</Notice>

***

## Request body

<ParamField body="name" type="string" required>
  Human-readable label for the config.
</ParamField>

<ParamField body="provider_config" type="object" required>
  Provider settings.

  * `provider` (string, optional): Secrets provider. Defaults to `onepassword`, the only supported value.
  * `op_vault_id` (string, required): Identifier of the 1Password vault to read credentials from.
</ParamField>

<ParamField body="token" type="string" required>
  The 1Password service account token granting access to the vault. Write-only: validated before storage and omitted from every response.
</ParamField>

***

## Examples

<CodeGroup>
  ```bash cURL theme={"system"}
  curl -X POST https://agp.eu.hcompany.ai/api/v2/vaults \
    -H "Authorization: Bearer $HAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "prod-1password",
      "provider_config": {"provider": "onepassword", "op_vault_id": "abcd1234efgh5678"},
      "token": "ops_eyJ..."
    }'
  ```

  ```python Python theme={"system"}
  from hai_agents import Client, OnePasswordConfig

  client = Client()

  vault = client.vaults.create_vault(
      name="prod-1password",
      provider_config=OnePasswordConfig(op_vault_id="abcd1234efgh5678"),
      token="ops_eyJ...",
  )
  print(vault.id)
  ```

  ```typescript TypeScript theme={"system"}
  import { HaiAgentsClient } from "hai-agents";

  const client = new HaiAgentsClient();

  const vault = await client.vaults.createVault({
    name: "prod-1password",
    providerConfig: { opVaultId: "abcd1234efgh5678" },
    token: "ops_eyJ...",
  });
  console.log(vault.id);
  ```
</CodeGroup>

```json Response theme={"system"}
{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "org_id": "1c9a2f6e-4b3d-4a8c-9e5f-7d6b8a0c1e2f",
  "name": "prod-1password",
  "provider_config": {"provider": "onepassword", "op_vault_id": "abcd1234efgh5678"},
  "created_at": "2026-05-07T14:30:00Z",
  "updated_at": "2026-05-07T14:30:00Z"
}
```

***

## Errors

| Status | Cause                                                                                           |
| ------ | ----------------------------------------------------------------------------------------------- |
| `409`  | A vault with this `name` already exists in your organization. Names are unique per org.         |
| `422`  | Body failed validation, or the provider rejected the token (it could not access `op_vault_id`). |