Browse docs+

Create Vault

Creates a new encrypted vault.

POST /api/v1/machine/vault

Important

All machine-created vaults are encrypted.
The vault name and dataClassification are metadata. They are protected in transit and at rest, but they are not end-to-end encrypted.
This write path no longer requires client-signed checkpoint payloads.
AGENT-scoped callers receive ADMIN access to the new vault. USER, TENANT, and ORG callers grant the acting org user ADMIN access.
If projectId is provided, that project is granted WRITE access to the new vault.

Headers

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

Request Body

Field	Type	Required	Description
`id`	string	Yes	Stable vault ID chosen client-side
`name`	string	Yes	Vault name, max 255 characters
`projectId`	string	No	Optional project ID to grant project-level `WRITE` access
`dataClassification`	string	No	`PUBLIC`, `INTERNAL`, `CONFIDENTIAL`, or `CUI`; defaults to `INTERNAL`

Response

Success (201 Created)

{
  "id": "507f1f77bcf86cd799439016"
}

Error Responses

400 Bad Request - Invalid body or create failure

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

404 Not Found - Project not found or not accessible

{
  "error": {
    "code": "project_not_found",
    "message": "The project with ID \"507f1f77bcf86cd799439014\" was not found or you do not have access to it."
  }
}

Example Request

curl -X POST "https://r4.dev/api/v1/machine/vault" \
  -H "X-API-Key: rk_abc123def456.ghijklmnopqrstuvwxyz" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "507f1f77bcf86cd799439016",
    "name": "Production Secrets",
    "projectId": "507f1f77bcf86cd799439014",
    "dataClassification": "CONFIDENTIAL"
  }'

Notes

This endpoint requires machine.vault.write.
The new vault is audit-logged and receives initial access permissions in the same transaction as creation.
Field values become end-to-end encrypted only when you create vault items with client-encrypted field envelopes.