Create Vault

Creates a new encrypted vault with scope-based default permissions.

POST /api/v1/machine/vault

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
`name`	string	Yes	The name of the vault (max 255 characters)
`encryptionKeyId`	string	Yes	The encryption key ID. Encryption is required for machine-created vaults.
`projectId`	string	No	Optional project ID to grant project-level WRITE access to the vault
`dataClassification`	string	No	Data classification level: `PUBLIC`, `INTERNAL`, `CONFIDENTIAL`, or `CUI`

Permissions

Default permissions are determined by the API key scope:

AGENT-scoped API keys: The agent is granted ADMIN access to the vault
USER/TENANT/ORG-scoped API keys: The session user is granted ADMIN access
If projectId is provided, the project is additionally granted WRITE access

Response

Success (201 Created)

{
  "id": "507f1f77bcf86cd799439016"
}

Response Fields

Field	Type	Description
`id`	string	The unique identifier of the newly created vault

Error Responses

400 Bad Request - Invalid request body or vault creation failed

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

404 Not Found - Encryption key or project not found

{
  "error": {
    "code": "encryption_key_not_found",
    "message": "The encryption key with the provided ID 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 '{
    "name": "Production Secrets",
    "encryptionKeyId": "507f1f77bcf86cd799439015",
    "projectId": "507f1f77bcf86cd799439014",
    "dataClassification": "CONFIDENTIAL"
  }'

Use Cases

Environment provisioning: Automatically create vaults for new environments or projects
Team onboarding: Set up secret storage as part of team provisioning workflows
Compliance: Create CUI-classified vaults for controlled unclassified information
Agent deployment: Create dedicated vaults for AI agent credential storage