◍ /v1/vault

Vault — your secrets are yours.

AES-256-GCM with HKDF-derived per-project keys. Versioned and audit-logged. Restricted value reads require an owned active audience member and its exact-request root proof; project bearers retain administration.

Default values are server-encrypted, not end-to-end encrypted. The running service derives their keys and can read them. Use agent_encrypted=true only when your client supplies ciphertext the server should not decrypt.

Model

Per-project derived key. HKDF derives it from one platform-wide VAULT_MASTER_KEY plus the project ID and fixed vault-v1 context. There is no epoch rotation. Compromise of the platform master can expose all default server-encrypted vault values.
Versioned secrets. Every PUT creates a new version. Previous versions stay readable until explicitly deleted.
Audience. agent_ids: null shares within the project; [] denies value reads; a nonempty list selects owned identity UUIDs. Restricted HTTP reads require X-Agent-Id plus the selected active identity's root proof. Hosted runtime consumers check their durable identity against the same audience and write read/denial audits.
Server-side at-rest encryption. Vault value columns store ciphertext. The running service receives plaintext for default-mode writes and reads and derives keys from VAULT_MASTER_KEY; this is not end-to-end opacity or a whole-host no-plaintext guarantee.

Project bearers can change audiences and read metadata; these checks do not isolate identities from a project administrator. Invalid legacy audiences fail closed. See identity partitions for proof, replay and custody boundaries.

Endpoints

PUT /v1/vault/:name Bearer required

Store or update a secret. Each PUT increments the version. Subsequent GETs return the latest unless ?version= is specified.

Field	Type	Description
valuerequired	string	The plaintext secret. Encrypted server-side before write.
tagsoptional	string[]	Searchable tags — e.g. `["openai", "production"]`.
descriptionoptional	string	Human-readable note. Surfaces in the wake's `you_keep`.
agent_idsoptional	string[] \| null	Up to 100 owned active UUID or `did:at:UUID` selectors, normalized to a sorted unique audience. Omission preserves an existing policy; a new omitted policy is `null`. Explicit `null` shares within the project; `[]` denies value reads.
rotation_due_atoptional	timestamptz	Optional rotation reminder. Surfaces in the wake.

curl

curl -X PUT https://api.agenttool.dev/v1/vault/openai-key \
  -H "Authorization: Bearer $AT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "sk-...",
    "tags": ["openai", "production"],
    "description": "OpenAI API key for embeddings"
  }'

GET /v1/vault/:name Bearer required

Read the current version, or a positive integer ?version=N. Restricted audiences require the selected identity's identity-read-authority/v1 proof over the exact GET path and query, using X-Agenttool-Authority-* headers. Changing the version query requires a matching proof. Successful value reads and audience denials append audit records; a missing secret has no per-secret receipt.

GET /v1/vault Bearer required

List secret names + metadata only. Values are never returned by list. Filter by tag.

DELETE /v1/vault/:name Bearer required

Soft-delete the secret. The row and stored version ciphertext remain in the database; values are not zeroed.

GET /v1/vault/:name/versions Bearer required

List all versions of a secret with their write timestamps. Pair with GET ?version=N for rollback.

GET /v1/vault/:name/audit Bearer required

Ordinary access-log rows for HTTP and hosted runtime reads, writes and audience denials. A successful restricted HTTP read records the proved identity; runtime reads record the checked runtime subject. Unverified header labels are not attributed as authenticated actors. Rows are not signed, hash-chained, or database-immutable.

PUT /v1/vault/:name/policy Bearer required

Replace the audience without rotating the value. Requires project bearer administration; the same null, empty-set and owned-identity rules apply to HTTP and runtime value reads. This policy write is not an authenticated identity action.

Bulk operations

POST /v1/vault/bulk Bearer required

Write up to 50 secrets. All supplied audiences are validated before the first write; value writes are sequential, not one atomic transaction. Omitting an audience preserves an existing policy.

Vault and execute are separate

/v1/execute is disabled by default and does not inject vault values. Do not embed a project bearer or private provider key in hosted execute source, even when an operator explicitly enables the unsafe legacy path. Read the current process and network boundary at /public/safety.

Fetch and decrypt a secret on infrastructure you control and call the provider there. The optional legacy Python and bash path can make outbound calls from AgentTool infrastructure, so its code, traffic, and process memory are not an agent-only privacy boundary.

Vault — your secrets are yours.

Model

Endpoints

Bulk operations

Vault and execute are separate

What to read next