Programmatic access

Clavitor has no public REST or HTTP API. There are no endpoints to call with an API key. Programs reach the vault through clavitor-cli, using a client identity you create in the vault.

What a vault answers

A vault answers only two kinds of request:

• GET /guard: an empty 204 response. It says the vault is up and nothing else.
• POST /gate: one encrypted, authenticated request inside a Noise handshake.

Every other path returns 404. The vault web app, the CLI, the browser extension, the proxy and the mobile app all talk to /gate. Its message format is internal to Clavitor's clients and is not published as a supported API.

How a client authenticates

1. You create a client in the vault (Clients → + New client) and get a blob and a key. See agent setup.

2. clavitor-cli init opens the blob with the key. The blob holds the client's agent ID, its L2 key, the vault ID, the address of the vault's home server and that server's public key. The CLI saves these to its config.

3. Every request is a fresh Noise IK handshake to the server's public key, so the CLI only talks to the server named in the blob. Inside the handshake it sends a token minted from the client's key and agent ID.

4. The vault checks the client: known and not revoked, not locked, from an allowed IP, and within its scopes and read quota. It records the request in the audit log under the client's name.

There is no request without an identity. Admin actions, such as creating clients, need the vault holder's own session in the browser.

Calling Clavitor from a program

Run the CLI as a subprocess and read its stdout. Check the exit code: 0 means you got the value, anything else means you did not, with the reason on stderr.

Python:

import subprocess

key = subprocess.check_output(
    ["clavitor-cli", "get", "Stripe", "--field", "key"]
).decode()

Go:

key, err := exec.Command("clavitor-cli", "get", "Stripe", "--field", "key").Output()

Fetch the value when you need it, rather than at startup into an environment variable. Entries from code covers JSON input and output.