REST API Overview & Authentication

The Vertueal Password Manager REST API enables developers to programmatically synchronize encrypted vaults, interrogate hardware device trust, and generate ephemeral burn-on-read credential shares.

Base URLs & Protocols

All API communication requires HTTPS with TLS 1.3:

Authentication & Cryptographic Verification

Because Vertueal operates on a Zero-Knowledge Architecture, API authentication requires two distinct layers:

1. User Identification: The userId (or OAuth access token) identifies which vault record to target.
2. Cryptographic Proof of Knowledge (authHash):
   • Rather than sending an API secret or master password over the network, client applications must compute an authHash using HMAC-SHA256:

   // Client-side derivation
   const authKey = await crypto.subtle.deriveKey(
       { name: "PBKDF2", salt: textEncoder.encode(salt + "_AUTH"), iterations: 100000, hash: "SHA-256" },
       masterPasswordMaterial,
       { name: "HMAC", hash: "SHA-256" },
       false,
       ["sign"]
   );
   const signature = await crypto.subtle.sign("HMAC", authKey, textEncoder.encode("server-auth-check"));
   const authHash = Array.from(new Uint8Array(signature)).map(b => b.toString(16).padStart(2, '0')).join('');

3. Hardware Device Header (x-device-id):
   • All sensitive vault read/write operations require an x-device-id HTTP header matching a verified UserDevice record:

   x-device-id: client-550e8400-e29b-41d4-a716-446655440000

Rate Limiting Policies

The API enforces strict distributed sliding-window rate limits powered by Redis. If you exceed these limits, the API returns HTTP 429 Too Many Requests with a Retry-After header:

Standard Error Response Format

Errors are returned as standard JSON objects with HTTP 4xx or 5xx status codes:

{
  "error": "Device not verified",
  "details": {
    "deviceId": "client-550e8400-e29b-41d4-a716-446655440000",
    "requiresMfa": true
  }
}

Common HTTP Status Codes:

• 200 OK: Request succeeded.
• 400 Bad Request: Payload validation failed against Zod schema.
• 401 Unauthorized: Invalid authHash or expired session.
• 403 Forbidden: Device unrecognized or unverified (x-device-id missing/untrusted).
• 404 Not Found: Vault or ephemeral share not found.
• 429 Too Many Requests: Rate limit window exceeded.
• 500 Internal Server Error: Server error logged with structured Winston audit ID.