Public API reference

VaultPilot public integration clients are read-only identities for approved systems. They expose encrypted vault snapshots and operational status metadata only. The public API never returns plaintext passwords, master passwords, decrypted vault payloads or private server material.

Create clients from the Owner-only API client section under Integrations. Each client has a generated client ID that starts with pmc_ and a one-time client secret that starts with pms_. The secret is stored on the server only as a keyed digest; if it is lost, create a replacement client and revoke the old one.

Public v1 endpoints are GET-only read endpoints. Do not send a request body; requests that include one are rejected.

Authentication

New integrations use HTTP Basic authentication:

Authorization: Basic ${BASE64_CLIENT_CREDENTIALS}

Older clients can use the legacy compatibility headers:

x-passman-client-id: <CLIENT_ID>
x-passman-client-secret: <CLIENT_SECRET>

Do not log either header. Do not paste real client IDs, client secrets, encrypted payloads, vault IDs or secret IDs into screenshots, tickets, documents or support email.

Malformed or oversized credentials are rejected before VaultPilot looks up the client.

Scopes and endpoints

Scope	Endpoint	Response
`SECRETS_READ`	`GET /api/public/v1/secrets`	Encrypted vault and secret snapshots for the vaults assigned to the API client.
`SECRETS_READ`	`GET /api/public/v1/secrets/{secretId}`	One encrypted secret from the assigned-vault snapshot. The ID must be a UUID.
`SERVER_STATUS_READ`	`GET /api/public/v1/server/status`	App version, uptime, vault count, active API client count and directory provider count.
`DIRECTORY_STATUS_READ`	`GET /api/public/v1/directory/status`	Directory provider health, object counts, selected login and credential counts, last-seen timestamps and sync timestamps.
`UPDATE_STATUS_READ`	`GET /api/public/v1/updates/status`	Update Center status for read-only monitoring.

SECRETS_READ requires at least one assigned vault. Status-only clients can be created without vault assignment.

Request examples

PowerShell Basic auth example:

$pair = "<CLIENT_ID>:<CLIENT_SECRET>"
$basic = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($pair))
Invoke-RestMethod -Headers @{ Authorization = "Basic $basic" } -Uri "https://<SERVER_HOST>:1734/api/public/v1/server/status"

Compatibility-header example:

Invoke-RestMethod `
  -Headers @{
    "x-passman-client-id" = "<CLIENT_ID>"
    "x-passman-client-secret" = "<CLIENT_SECRET>"
  } `
  -Uri "https://<SERVER_HOST>:1734/api/public/v1/secrets"

Keep real values in the consuming system’s approved secret store. Run commands that contain them only in a private operator shell.

Response shape

Secret snapshot responses are encrypted data packages, not decrypted records:

{
  "mode": "ENCRYPTED_SNAPSHOT",
  "vaults": [
    {
      "id": "<VAULT_ID>",
      "nameEncrypted": "<ENCRYPTED_VAULT_NAME>",
      "secrets": [
        {
          "id": "<SECRET_ID>",
          "type": "LOGIN",
          "payloadEncrypted": "<ENCRYPTED_PAYLOAD>",
          "updatedAt": "<ISO_TIMESTAMP>"
        }
      ]
    }
  ]
}

Status endpoints return operational metadata only. They do not decrypt vault content.

Status and error contract

Public API responses include Cache-Control: no-store, so browsers and proxies do not cache snapshots. Public v1 endpoints are rate-limited to 120 requests per minute.

Status	Meaning	Operator action
`200`	The client is authenticated and authorized for the requested read-only endpoint.	Consume the encrypted snapshot or status metadata.
`401`	Client ID or secret is missing, malformed, wrong or revoked.	Create a replacement client, update the consuming system and revoke the old client.
`403`	The client lacks the required scope, vault assignment or secret authorization.	Confirm scope, vault assignment and intended endpoint. Secret lookups that are malformed, deleted or outside the allowed vault list return `403 Integration authorization failed.`

Back to Documentation