Browse docs+

Create Vault Item

Creates a new vault item with fields in the specified vault.

POST /api/v1/machine/vault/:vaultId/items

Important

This write path no longer requires client-signed summary or detail checkpoints.
The client must still choose stable vault-item, field, and field-instance IDs.
Item names, field labels, websites, item type, and environment-variable flags are metadata, so they are not end-to-end encrypted.
Every secret field value must already be a client-encrypted v3 vault envelope before it reaches the API.
The backend stores encryptedValue as-is; it does not decrypt or transform field values.

Headers

Header	Type	Required	Description
`X-API-Key`	string	Yes	Your machine API key
`Content-Type`	string	Yes	Must be `application/json`

Path Parameters

Parameter	Type	Required	Description
`vaultId`	string	Yes	The unique identifier of the vault to add the item to

Request Body

Field	Type	Required	Description
`id`	string	Yes	Stable vault-item ID chosen client-side
`name`	string	Yes	Vault-item name, max 255 characters
`type`	string	Yes	Item type, for example `LOGIN`
`websites`	string[]	No	Associated website URLs
`fields`	array	Yes	Fields to create on the vault item

Field Object

Field	Type	Required	Description
`id`	string	Yes	Stable field ID chosen client-side
`fieldInstanceId`	string	Yes	Stable field-instance ID chosen client-side
`name`	string	Yes	Field label, for example `Username`
`type`	string	Yes	Field type
`encryptedValue`	string \| null	No	Client-encrypted v3 vault envelope for the field value
`isEnvironmentVariable`	boolean \| null	No	Marks the field for environment-variable export tooling

Response

Success (201 Created)

{
  "id": "507f1f77bcf86cd799439014"
}

Error Responses

400 Bad Request - Invalid body or create failure

{
  "error": {
    "code": "vault_item_creation_failed",
    "message": "Failed to create the vault item. Please verify your input and try again."
  }
}

404 Not Found - Vault not found or not accessible

{
  "error": {
    "code": "vault_not_found",
    "message": "The vault with ID \"abc123\" was not found or you do not have access to it."
  }
}

Example Request

curl -X POST "https://r4.dev/api/v1/machine/vault/507f1f77bcf86cd799439011/items" \
  -H "X-API-Key: rk_abc123def456.ghijklmnopqrstuvwxyz" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "507f1f77bcf86cd799439014",
    "name": "Production Database",
    "type": "LOGIN",
    "websites": ["https://db.example.com"],
    "fields": [
      {
        "id": "507f1f77bcf86cd799439019",
        "fieldInstanceId": "507f1f77bcf86cd799439051",
        "name": "Username",
        "type": "TEXT",
        "encryptedValue": "{\"v\":3,\"iv\":\"...\",\"t\":\"...\",\"d\":\"...\"}"
      },
      {
        "id": "507f1f77bcf86cd799439020",
        "fieldInstanceId": "507f1f77bcf86cd799439052",
        "name": "Password",
        "type": "PASSWORD",
        "encryptedValue": "{\"v\":3,\"iv\":\"...\",\"t\":\"...\",\"d\":\"...\"}",
        "isEnvironmentVariable": true
      }
    ]
  }'

Notes

This endpoint requires machine.vault.write plus access to the parent vault.
action: update flows later create new field instances; this create endpoint creates the initial active field instances.
Field type controls client presentation and masking, not whether a value is encrypted.