Specification for fetching public salt metadata, reading encrypted ciphertext, syncing updates, and rotating master keys.

Vault API Endpoints

The Vault API provides endpoints for fetching salt metadata, synchronizing encrypted ciphertext blobs, and performing master password rotations.

1. Fetch Vault Metadata or Ciphertext

GET /api/vault

This endpoint operates in two modes:

Public Metadata Mode (No authHash): Returns the cryptographic salt and version, allowing client applications to derive the MEK locally.
Authenticated Retrieval Mode (With authHash): Returns the encrypted ciphertext data_blob once device trust and authentication hash match.

Query Parameters:

Parameter	Type	Required	Description
`userId`	`string`	Yes	The user's unique identity identifier.
`authHash`	`string`	Optional	The HMAC-SHA256 authentication proof. Omit to fetch public salt.
`email`	`string`	Optional	Registered user email for dispatching security alert emails upon unlock.

Required Headers (When `authHash` is supplied):

Header	Value	Description
`x-device-id`	`string`	Verified hardware device identifier.

Code Examples:

cURL (Fetch Public Salt)

curl -X GET "https://passwordmanager.vertueal.com/api/vault?userId=usr_01j8m2k9p3x4y5z6"

cURL (Fetch Encrypted Ciphertext)

curl -X GET "https://passwordmanager.vertueal.com/api/vault?userId=usr_01j8m2k9p3x4y5z6&authHash=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855&email=user@example.com" \
  -H "x-device-id: client-550e8400-e29b-41d4-a716-446655440000"

Response (200 OK):

{
  "exists": true,
  "blob": "YWJjZGVmMTIzNDU2...base64_ciphertext...",
  "salt": "7f8b9c0d1e2f3a4b",
  "version": 4
}

2. Sync Vault Changes

POST /api/vault

Saves or updates the user's encrypted vault payload. Requires an authorized device.

Request Headers:

Content-Type: application/json
x-device-id: client-550e8400-e29b-41d4-a716-446655440000

Request Body Schema:

Field	Type	Required	Description
`userId`	`string`	Yes	User identifier.
`blob`	`string`	Yes	Base64-encoded encrypted vault payload (AES-256-GCM).
`authHash`	`string`	Yes	HMAC-SHA256 authentication verification hash.
`salt`	`string`	Yes	Cryptographic salt used for key derivation.
`recovery_blob`	`string`	Optional	Base64-encoded wrapped MEK recovery payload.
`recovery_salt`	`string`	Optional	Salt used for recovery key derivation.

Request Payload

{
  "userId": "usr_01j8m2k9p3x4y5z6",
  "blob": "ENCRYPTED_BASE64_PAYLOAD...",
  "authHash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "salt": "7f8b9c0d1e2f3a4b",
  "recovery_blob": "WRAPPED_RECOVERY_BLOB...",
  "recovery_salt": "9a8b7c6d5e4f3a2b"
}

Response (200 OK):

{
  "success": true
}

3. Rotate Master Password

POST /api/vault/rotate

Re-encrypts the vault with a new master key, updates the server authentication hash, and atomically increments the vault version. Requires valid email MFA code verification.

Request Body:

{
  "userId": "usr_01j8m2k9p3x4y5z6",
  "email": "user@example.com",
  "blob": "NEW_RE_ENCRYPTED_BLOB...",
  "authHash": "NEW_AUTH_HASH...",
  "salt": "NEW_CRYPTOGRAPHIC_SALT...",
  "mfaCode": "849201",
  "recovery_blob": "NEW_WRAPPED_RECOVERY_BLOB...",
  "recovery_salt": "NEW_RECOVERY_SALT..."
}

Response (200 OK):

{
  "success": true,
  "version": 5
}

Vault API Endpoints

On this page