Integration API clients

Use integration API clients when an approved system needs read-only VaultPilot data through the public API. Keep the client narrow: grant only the scopes and vaults the system needs, record who owns it, and revoke it when the integration is retired.

Public API surface

Endpoint, credential format and status-code details are in the Public API reference.

GET /api/public/v1/secrets returns an encrypted snapshot for the vaults assigned to the API client: vault metadata, encrypted vault names, secret IDs, secret types, encrypted payloads and timestamps. It does not return plaintext passwords or decrypted vault data.

GET /api/public/v1/secrets/{secretId} returns one encrypted secret from the same allowed snapshot. If the ID is malformed, missing, deleted, or outside the client’s allowed vaults, VaultPilot deliberately returns 403 Integration authorization failed. so unauthorized clients cannot tell hidden records from bad IDs.

API clients can also read status endpoints. These never decrypt vault data and need no vault assignment unless the client also has SECRETS_READ.

Create a client

1. Sign in as an Owner.
2. Open Integrations and go to the API clients section.
3. Pick only the endpoint scopes the consuming system needs.
4. If SECRETS_READ is selected, assign the minimum vault list. Status-only clients do not need vault scope.
5. Create the client with a clear name.
6. Copy the client secret once and store it in the approved secret store for the consuming system.
7. Record owner, purpose, allowed vaults, scopes and review date.

The client secret is stored hashed on the server. If it is lost, create a new client and revoke the old one.

Authentication

VaultPilot accepts either HTTP Basic auth or the legacy compatibility headers. Prefer Basic auth for new integrations.

Authorization: Basic ${BASE64_CLIENT_CREDENTIALS}

Older clients can use the 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 or secrets into screenshots, tickets, documents or support email.

Example request

$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/secrets"

Status-only 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"

Run commands that contain real $pair or $basic values only in a private operator shell.

Expected errors

Related

• Public API reference
• Security and trust model
• Audit and security posture
• Knowledge base: API client access
• Support evidence pack

Back to Documentation →