Browse docs+

Create Vault

Creates a new encrypted vault.

POST /api/v1/machine/vault

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 ID and attach a signed, empty vault summary checkpoint.
The vault name is metadata, so it is not end-to-end encrypted. Only field values inside vault items are end-to-end encrypted.

Headers

Header	Type	Required	Description
`X-API-Key`	string	Yes	Your 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
`summaryCheckpoint`	object	Yes	Signed empty summary checkpoint for the new vault
`name`	string	Yes	The name of the vault (max 255 characters)
`projectId`	string	No	Optional project ID to grant project-level WRITE access
`dataClassification`	string	No	`PUBLIC`, `INTERNAL`, `CONFIDENTIAL`, or `CUI`

Permissions

USER/TENANT/ORG callers grant the session user ADMIN access to the new vault.
AGENT-scoped callers grant the acting agent ADMIN access to the new vault.
If projectId is provided, that project is additionally granted WRITE access.

Response

Success (201 Created)

{
  "id": "507f1f77bcf86cd799439016"
}

Error Responses

400 Bad Request - Invalid checkpoint or create failure

{
  "error": {
    "code": "vault_creation_failed",
    "message": "Failed to create the vault. 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 - 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",
    "summaryCheckpoint": {
      "checkpoint": {
        "vaultId": "507f1f77bcf86cd799439016",
        "version": 1,
        "name": "Production Secrets",
        "dataClassification": "CONFIDENTIAL",
        "currentDekVersion": 1,
        "items": [],
        "groups": []
      },
      "signerUserKeyPairId": "507f1f77bcf86cd799439099",
      "signerEncryptionKeyId": null,
      "signature": "base64-signature"
    },
    "name": "Production Secrets",
    "projectId": "507f1f77bcf86cd799439014",
    "dataClassification": "CONFIDENTIAL"
  }'

Notes

New vaults must start with an empty summaryCheckpoint.items and summaryCheckpoint.groups array.
The summaryCheckpoint name and data classification must match the top-level request fields.
Exactly one signer identifier should be present on the checkpoint: signerUserKeyPairId for human-backed callers or signerEncryptionKeyId for AGENT callers.