# Sync to OpenAI Vault

OpenAI-hosted Agents API sandboxes can use [vault credentials](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults)
without receiving their real values. OpenAI's network proxy substitutes a
credential only on requests to its approved HTTPS hosts. Seekrit can create and
rotate those vault credentials from a selected environment.

| At a glance | |
| --- | --- |
| **What seekrit writes** | One `environment_variable` vault credential per synced secret |
| **Addressed by** | An existing OpenAI vault ID (`vault_…`) and exact allowed hostnames |
| **Connection carries** | An OpenAI project API key |
| **Key permissions** | `api.vaults.read` and `api.vaults.write` |
| **Takes effect** | In a **new** Agents API session that attaches the vault |
| **Value visibility** | OpenAI holds the real value; the sandbox sees a placeholder |

Read [Third-party sync](/docs/guides/third-party-sync) first for the shared
decryption grant, filtering, name mapping, and deletion behavior.

> **Warning:** Enabling sync grants seekrit's sync engine decryption access to this environment and copies the selected values to OpenAI Vault. If the values must remain on infrastructure you control, use a [proxy you run](/docs/guides/frameworks/openai-agents-api#the-shape-that-works-a-placeholder-and-a-proxy-you-run) instead.

## 1. Create the connection

Create a vault in your OpenAI project, then create a project API key with
`api.vaults.read` and `api.vaults.write`. The key must be able to access that
vault. Enter the key in **Sync → Add connection** in the dashboard, or pipe it
to the CLI:

```bash
printf '%s' "$OPENAI_PROJECT_KEY" \
  | seekrit sync connect --name openai-agent --provider openai-vault
```

Use a project key dedicated to this connection. Seekrit encrypts it before
storing it, and only the sync engine can open the connection credential.

## 2. Bind an environment

Choose the vault ID and the exact HTTPS hostnames that may receive the
credentials. `--openai-hosts` takes hostnames without schemes, ports, paths, or
wildcards. Every credential in one binding gets the same host list. Use separate
bindings and environments when different credentials need different host access.

```bash
seekrit sync verify openai-agent --provider openai-vault \
  --openai-vault vault_123 --openai-hosts api.github.com

seekrit sync enable --connection openai-agent --provider openai-vault \
  --openai-vault vault_123 --openai-hosts api.github.com \
  --app support-agent --env hosted --include 'GITHUB_TOKEN' \
  --acknowledge-decryption
```

Verification checks vault access and reads credential metadata; it never
retrieves existing secret values. The binding's first push creates credentials
with a `secret_name` matching each destination name. Later pushes update only
credentials tagged with this seekrit binding's ID. A collision with another vault
credential fails that name rather than overwriting it. Removing a name follows
the binding's **delete** or **retain** setting; delete only removes a uniquely
matched credential owned by this binding.

OpenAI reserves `PATH`, `OPENAI_API_KEY`, and names beginning with `CODEX_` in
hosted environments. Seekrit rejects those destination names during sync. Map
them to other names if appropriate.

## 3. Attach the vault to a new session

Attach the vault ID to the Agents API session. The sandbox network policy must
also allow each hostname used by a vault credential. Keep the vault's real
values out of the session's `env` map: code running in the sandbox can read
that map.

```python
session = client.beta.agents.sessions.create(
    agent={"model": "gpt-6-astra", "instructions": "Use the configured tools."},
    environment={
        "type": "openai_hosted",
        "network": {
            "access": "restricted",
            "allowed_domains": ["api.github.com"],
        },
    },
    vault_ids=["vault_123"],
)
```

Check the [OpenAI vault guide](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults)
for how its placeholders are used in outbound requests. A value changed by
seekrit sync is available to **new** sessions. OpenAI does not update an
existing sandbox after a vault credential changes, so create a new session
after rotation.

## Troubleshooting

| Symptom | Check |
| --- | --- |
| Verify fails with `401` or `403` | The project key and its `api.vaults.read` / `api.vaults.write` permissions |
| Verify fails with `404` | The vault ID and whether the key belongs to its project |
| One name fails with a collision | A vault credential already uses that `secret_name`; choose another name or remove the unrelated credential yourself |
| A rotated value is not used | Start a new session and attach the vault ID |
| An outbound request is blocked | Add its exact hostname to both the credential's allowed hosts and the sandbox's restricted network policy |

## See also

- [OpenAI Agents API](/docs/guides/frameworks/openai-agents-api) — choose between native Vault and a proxy you operate
- [Third-party sync](/docs/guides/third-party-sync) — grants, name mapping, and deletion policy