Skip to main content
POST
Create a credential vault

Authorizations

Authorization
string
header
required

A Recursion API key, created in the console under API keys.

Headers

Idempotency-Key
string

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.

Required string length: 1 - 256
Pattern: ^[!-~]+$
x-tenant-id
string

Optional tenant consistency check. When present, it must name the tenant bound to the API key, including when x-organization-id is default.

Minimum string length: 1
x-organization-id
string

Organization 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.

Minimum string length: 1

Body

application/json

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.

display_name
string
required

Operator-facing label for the vault, shown wherever grants are reviewed. Required, and not blank; surrounding whitespace is trimmed.

Maximum string length: 256
Pattern: \S
metadata
object

Free-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.

created_at
string<date-time>
required

RFC 3339 timestamp of when this record was created. Server-assigned.

credential_count
integer
required

How many credentials this vault currently holds, so a list view need not fetch each vault's credentials.

Required range: -9007199254740991 <= x <= 9007199254740991
display_name
string
required

Operator-facing label for the vault, shown wherever vaults are listed.

organization_id
string
required

Organization that owns this record. Resolved from the API key; never accepted from the caller.

updated_at
string<date-time>
required

RFC 3339 timestamp of the last change to this record. Server-assigned.

vault_id
string
required

Identifier for this vault (UUID). Server-assigned.

metadata
object

Free-form caller-supplied key/value labels. Stored verbatim and never interpreted by the service.