Skip to main content
See the Credential vault guide for the injection model.
A vault holds credentials an agent needs but must never see. Secret values are write-only: they are accepted on create, injected at runtime, and never returned by any read.

​
The vault object

​
string
Unique id (e.g. vlt_01H...).
​
string
Always vault.
​
string | null
The identity the vault belongs to, or null when it was created without one.
​
string
Human-readable name.
​
integer
How many credentials it holds. The metadata itself comes from GET /v1/vaults/{id}/credentials — a vault read never embeds it.
​
string
Creation timestamp.

​
Create a vault

POST /v1/vaults — scope admin
​
string
required
Human-readable name.
​
string
The identity that owns the vault. Defaults to null.

​
Add a credential

POST /v1/vaults/{id}/credentials
​
string
required
One of env_var, static_bearer, or mcp_oauth. env_var is refused with feature_not_configured — substituting it needs an egress boundary on the sandbox’s network path, and storing a secret under a guarantee that cannot be kept is worse than refusing it. Use an MCP kind, which is injected before the sandbox sees the value.
​
string
required
The reference name — for env_var, the environment variable name (e.g. PAYMENTS_API_KEY).
​
string
Required for env_var — the one exact destination host the value may be substituted for. Never a wildcard.
​
string
Required for static_bearer and mcp_oauth — the server URL the token is matched to.
​
string
The one agent the token may be injected into. Omitted, any agent that declares mcp_server_url receives it. Fixed at create, like every other field: to re-bind, create a new credential and delete the old one.
​
string
required
The secret. Write-only — accepted here and never returned by any endpoint.
​
string
Optional expiry, as an RFC 3339 timestamp with an offset.
Reads never include secret values. GET on a credential returns only metadata — kind, key, host, mcp_server_url, agent_id, placeholder_ref, expires_at, last_injected_at, created_at. There is no reveal route and no update route: rotation is create-new then delete-old.

​
How injection works

  • env_var — not available on this deployment. The design is an opaque placeholder in the sandbox with the real value substituted at the egress boundary; that boundary does not exist yet, so the route refuses the kind rather than storing a secret it cannot protect.
  • static_bearer / mcp_oauth — injected server-side when the agent connects to the matching MCP server URL. Matching is by URL: a credential is injected when its mcp_server_url equals one of the agent version’s mcp_servers[].url. A credential with an agent_id is injected into that agent’s sessions only. A credential for this platform’s own /v1/mcp is never injected: bound to an agent, it marks that agent as your organization’s CEO, which gets a short-lived credential for each turn holding only what the people driving it may do. There is no per-session credential selection.
  • A bound agent is an admin’s to change. Once a credential is bound to an agent, PATCH, rollback and DELETE on that agent need the admin scope. Without it they answer 403 forbidden. A session, schedule or team roster pinned to a version older than the binding runs without the credential, unless that version is still the agent’s current one.
At rest, each value is protected with envelope encryption: a per-record data key (AES-256-GCM) wrapped by a managed key service and bound to the organization and identity.

​
Scopes

Writing a secret is an admin act; listing what exists is not. That split lets an agent-facing key confirm a credential is present without ever being able to add or remove one.

​
Retrieve a vault

GET /v1/vaults/{id} — scope agents:read. Returns the vault object with credential_count. Metadata only, like every other read here — no secret value is reachable through this or any route.
Response

​
List vaults & credentials

Both accept limit and after. See Pagination.

​
Delete

Deleting a vault soft-deletes the record and hard-deletes its secrets. The credential values are destroyed, not archived — this cannot be undone, and any agent that was relying on injection from this vault starts failing at the egress boundary on its next call.
Response

​
Rotating a credential

There is no update route for a credential, and that is the contract rather than an omission. Rotate by adding the new secret and then deleting the old one — two records, two ids. That keeps last_injected_at attributable to exactly one secret, so an audit can still answer which value was in use at the moment of a given call.

Back to core resources

The Phase 1 resource set.