Read-only API: approved systems read, never plaintext

An API client is a read-only identity for one approved system. The Owner chooses its scopes and, when vault data is needed, the vaults it may read. Vault data comes back only as encrypted snapshots; the API never returns plaintext passwords or decrypted vault data.

Access: Read only
Secret responses: Encrypted snapshots
Credentials: Client ID and one-time secret
Set up by: Owner

Illustration of an API client reading encrypted snapshots across the VaultPilot trust boundary

Four read scopes

Each scope opens one area. The vault-data scope returns encrypted snapshots for the assigned vaults and needs at least one vault. The three status scopes return operational information and need no vault, because they never decrypt anything.

Client ID and one-time secret

For a new client, VaultPilot generates a client ID and a secret. The secret is shown once, and the server keeps only a protected fingerprint of it. The consuming system sends both values with every request; the API guide shows how.

Responses and error codes

A vault-data response carries vault and secret identifiers, encrypted vault names, secret types, encrypted content and timestamps. Every response is marked so that browsers and servers in between do not cache it. VaultPilot rejects requests that try to send data, and too many requests in a short time are refused for a while.

Replacing and revoking a client

A revoked client stays in the client list, cannot be reactivated and cannot return the same secret. To change a secret, issue a new least-privilege client, move the consuming system to it, then revoke the old one. Successful use updates Last read and records the access in the audit history, once every few minutes per client rather than on every request.