Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

API Reference

Vault's backend API is built with Hono and runs on Cloudflare Workers, providing a fast, globally distributed API.

Base URLs

EnvironmentBase URL
Productionhttps://vault-api.workers.dev
Staginghttps://vault-api-staging.workers.dev

Authentication

Most endpoints require a valid JWT token in the Authorization header:

curl -H "Authorization: Bearer <token>" \
  https://vault-api.workers.dev/vault

API Sections

Authentication

WebAuthn registration, login, and session management.

Vaults

Create, read, update, and delete encrypted vaults.

Sharing

Vault sharing invitations and shared vault access.

Quick Reference

Authentication Endpoints

MethodEndpointDescription
POST/auth/register/optionsGet WebAuthn registration options
POST/auth/register/verifyComplete registration
POST/auth/login/optionsGet WebAuthn login options
POST/auth/login/verifyComplete login
POST/auth/session/logoutEnd session
GET/auth/session/statusCheck authentication status

CLI Authentication

MethodEndpointDescription
POST/auth/cli/sessionCreate CLI auth session
GET/auth/cli/session/:idPoll session status
POST/auth/cli/session/:id/completeComplete CLI session

Vault Endpoints

MethodEndpointDescription
GET/vaultList owned vaults
POST/vaultCreate new vault
GET/vault/:nameGet vault data
PUT/vault/:nameUpdate vault
DELETE/vault/:nameDelete vault

Sharing Endpoints

MethodEndpointDescription
POST/vault/:name/shareShare vault with user
GET/sharedList shared vaults
GET/shared/:ownerId/:nameGet shared vault
GET/invitationsList pending invitations
POST/invitations/:id/acceptAccept invitation

Response Format

All responses are JSON with consistent structure:

Success Response

{
  "data": { ... },
  "success": true
}

Error Response

{
  "error": "Error message",
  "code": "ERROR_CODE",
  "success": false
}

Error Codes

CodeHTTP StatusDescription
UNAUTHORIZED401Missing or invalid token
FORBIDDEN403Insufficient permissions
NOT_FOUND404Resource not found
CONFLICT409Version conflict (optimistic locking)
VALIDATION_ERROR400Invalid request data

Rate Limiting

API requests are rate-limited per IP address:

Endpoint TypeLimit
Auth endpoints10 req/min
Vault operations100 req/min
Read operations1000 req/min

TypeScript Client

Use the typed Hono client for type-safe API calls:

import { createClient } from "@pwm/api";
 
const api = createClient("https://vault-api.workers.dev", token);
 
// Fully typed responses
const vaults = await api.vault.$get();
const vault = await api.vault[":name"].$get({ param: { name: "default" } });

Next Steps