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 endpoint requires a trusted checkpoint signer.
USER, TENANT, and ORG API keys must use an active user key pair.
AGENT-scoped API keys must use signerEncryptionKeyId matching the agent's active registered encryption key.
The client must pre-allocate the vault-item, field, and field-instance IDs and attach signed summary/detail checkpoints.
Item names, field labels, and websites are metadata, so they are not end-to-end encrypted. Only encryptedValue is end-to-end encrypted.
Every field value must already be a client-encrypted v3 vault envelope before it reaches the API.

Headers

Header	Type	Required	Description
`X-API-Key`	string	Yes	Your 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
`summaryCheckpoint`	object	Yes	Signed replacement vault summary checkpoint for the parent vault
`detailCheckpoint`	object	Yes	Signed detail checkpoint for the new item
`name`	string	Yes	The name of the vault item (max 255 characters). This metadata is not end-to-end encrypted.
`type`	string	Yes	The item type (for example `LOGIN`)
`websites`	string[]	No	Associated website URLs. This metadata is not end-to-end encrypted.
`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	The field label (for example `Username`). This metadata is not end-to-end encrypted.
`type`	string	Yes	The field type
`encryptedValue`	string	No	Client-encrypted v3 vault envelope for the field value

Response

Success (201 Created)

{
  "id": "507f1f77bcf86cd799439014"
}

Error Responses

400 Bad Request - Invalid checkpoint, 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."
  }
}

403 Forbidden - Caller cannot satisfy zero-trust checkpoint requirements

{
  "error": {
    "code": "checkpoint_signer_required",
    "message": "Machine write endpoints require either a USER, TENANT, or ORG API key backed by an active user key pair, or an AGENT-scoped API key backed by the agent's active encryption key."
  }
}

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",
    "summaryCheckpoint": {
      "checkpoint": {
        "vaultId": "507f1f77bcf86cd799439011",
        "version": 9,
        "name": "Production Secrets",
        "dataClassification": "CONFIDENTIAL",
        "currentDekVersion": 3,
        "items": [
          {
            "id": "507f1f77bcf86cd799439014",
            "name": "Production Database",
            "type": "LOGIN",
            "websites": ["https://db.example.com"],
            "groupId": null
          }
        ],
        "groups": []
      },
      "signerUserKeyPairId": "507f1f77bcf86cd799439099",
      "signature": "base64-signature"
    },
    "detailCheckpoint": {
      "checkpoint": {
        "vaultItemId": "507f1f77bcf86cd799439014",
        "vaultId": "507f1f77bcf86cd799439011",
        "version": 1,
        "name": "Production Database",
        "type": "LOGIN",
        "websites": ["https://db.example.com"],
        "groupId": null,
        "fields": [
          {
            "id": "507f1f77bcf86cd799439019",
            "name": "Username",
            "type": "TEXT",
            "order": 0,
            "fieldInstanceIds": ["507f1f77bcf86cd799439051"],
            "assetIds": []
          }
        ]
      },
      "signerUserKeyPairId": "507f1f77bcf86cd799439099",
      "signature": "base64-signature"
    },
    "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\":\"...\"}"
      }
    ]
  }'

Notes

The backend stores encryptedValue as-is; it does not decrypt or transform field values.
The metadata inside summaryCheckpoint and detailCheckpoint, including names, field labels, and websites, is not end-to-end encrypted.
summaryCheckpoint authenticates the parent vault item listing after the create.
detailCheckpoint authenticates the new item's name, websites, and field layout.
Field type controls client masking, not whether the value is encrypted.