API Docs
Overview

API Reference

The vaultctl REST API is served at /api/v1. All requests and responses use JSON.

Base URL

https://your-vault-server.com/api/v1

Authentication

All endpoints except auth and health require a JWT access token in the Authorization header:

curl -H "Authorization: Bearer <access_token>" \
     https://vault.example.com/api/v1/vaults

Conventions

ConventionDetails
Content-Typeapplication/json
TimestampsISO 8601 UTC (2026-04-06T12:00:00Z)
Binary dataBase64 standard encoding (with = padding)
Encrypted blobsBase64-encoded wire format: version(1B) || alg_id(1B) || nonce || ciphertext || tag

Rate Limits

ScopeLimit
Per IP60 req/min
Per email (auth)5 attempts / 15 min

All Endpoints

Public

MethodPathDescription
GET/healthHealth check
GET/configServer config
POST/auth/registerCreate account
GET/auth/prelogin?email=Get KDF params
POST/auth/loginLog in
POST/auth/refreshRefresh tokens
POST/auth/logoutLog out
POST/invites/redeemRedeem invite token

Authenticated (JWT)

Authentication

MethodPathDescription
POST/auth/step-upRe-verify password
POST/auth/totp/setupGenerate TOTP (step-up)
POST/auth/totp/enableEnable 2FA
POST/auth/totp/disableDisable 2FA (step-up)
POST/auth/totp/verifyVerify TOTP code
POST/auth/password/changeChange password (step-up)

Vaults

MethodPathDescription
GET/vaultsList vaults
POST/vaultsCreate vault
POST/vaults/:id/membersShare vault (add member)
DELETE/vaults/:id/members/:userIdRemove member
POST/vaults/:id/rekeyRekey vault after member removal

Items

MethodPathDescription
GET/vaults/:id/itemsList items
POST/vaults/:id/itemsCreate item
GET/vaults/:id/items/:idGet item
PUT/vaults/:id/items/:idUpdate item
DELETE/vaults/:id/items/:idTrash item
GET/vaults/:id/trashList trash
POST/vaults/:id/trash/:id/restoreRestore item
DELETE/vaults/:id/trash/:idPurge item (step-up)
DELETE/vaults/:id/trashBulk purge expired trash (step-up)

Folders

MethodPathDescription
GET/vaults/:id/foldersList folders
POST/vaults/:id/foldersCreate folder
PUT/vaults/:id/folders/:idRename folder
DELETE/vaults/:id/folders/:idDelete folder

Users

MethodPathDescription
GET/users/meGet user profile
PUT/users/meUpdate user profile
GET/users/me/sessionsList active sessions
DELETE/users/me/sessions/:idRevoke session

Organizations

MethodPathDescription
POST/orgsCreate organization
GET/orgs/:id/membersList org members
PUT/orgs/:id/members/:userIdUpdate member role
GET/orgs/:id/members/:userId/pubkeyGet member public key

Invites

MethodPathDescription
POST/invitesCreate invite
GET/invites?orgId=List invites
DELETE/invites/:idRevoke invite
POST/invites/redeemRedeem invite (public)

API Keys

MethodPathDescription
POST/api-keysCreate API key
GET/api-keysList API keys
DELETE/api-keys/:idDelete API key

Import/Export

MethodPathDescription
GET/exportExport vault data (step-up)

Admin

MethodPathDescription
POST/admin/backupTrigger backup (CLI only, returns 501)
Authentication