Create a credential vault
Creates an empty credential vault and returns it with its generated vault_id. Vaults are the unit a session or agent is granted, so create one per trust boundary and add credential references to it afterwards. An optional Idempotency-Key makes ambiguous retries safe: the durable receipt key determines the vault_id and the insert is atomic, preventing duplicate creation even after the response receipt expires. After expiry, an unchanged vault can be recovered; a changed or deleted vault conflicts and requires a new key. Never retry an unkeyed create after an ambiguous transport failure.
Authorizations
A Recursion API key, created in the console under API keys.
Headers
Replay-protection key in an organization-wide namespace shared by keyed mutations. It must contain 1 to 256 visible ASCII characters and be sent as exactly one header value. Request identity is the exact HTTP method, escaped path, raw query, and raw body bytes. For the legacy automation-run route only, the historical fingerprint ignores top-level JSON formatting and object-key order and removes the retired top-level idempotency_key field. The same request replays the original successful response; any different request returns 409 idempotency_conflict, and an active matching request returns 409 idempotency_in_progress. Completed receipts are retained for approximately 24 hours, pending claims may be reclaimed after approximately 1 hour, and no deduplication is guaranteed after expiry.
1 - 256^[!-~]+$Optional tenant consistency check. When present, it must name the tenant bound to the API key, including when x-organization-id is default.
1Organization in which to act. Required for a tenant-scoped API key. Optional for an organization-scoped key, where it must name that same organization. The value may be an organization id or default.
1Body
Request body for creating a vault: the container that credentials are added to and that sessions are granted. Creating a vault stores no secret material of its own.
Operator-facing label for the vault, shown wherever grants are reviewed. Required, and not blank; surrounding whitespace is trimmed.
256\SFree-form caller-owned JSON stored with the vault and returned on reads. Not interpreted by the service; never put secret material here.
Response
A named group of credentials an agent session may be granted. A session references vaults by id; the credential values inside are resolved at execution time and are never returned over the API.
A named group of credentials an agent session may be granted. A session references vaults by id; the credential values inside are resolved at execution time and are never returned over the API.
RFC 3339 timestamp of when this record was created. Server-assigned.
How many credentials this vault currently holds, so a list view need not fetch each vault's credentials.
-9007199254740991 <= x <= 9007199254740991Operator-facing label for the vault, shown wherever vaults are listed.
Organization that owns this record. Resolved from the API key; never accepted from the caller.
RFC 3339 timestamp of the last change to this record. Server-assigned.
Identifier for this vault (UUID). Server-assigned.
Free-form caller-supplied key/value labels. Stored verbatim and never interpreted by the service.