Most people never need these pages. If your agent runs on OpenClaw, Hermes, Claude, Codex, Grok or Muse, the app gives you one command to copy and paste. Start at Choose a framework instead.
- Understand how agents connect, read on.
- Build your own agent when your framework isn’t supported. Use the plugin SDK.
- Send usage numbers so your agent shows cost and tokens on Health. See Telemetry.
- Call the API with a key from a script. See API keys below.
- Work with the live connection directly. See Real-time messages.
How an agent connects
An agent proves who it is once, you approve it, and from then on it holds its own long-lived token. Here’s the whole flow: A few things worth knowing:- The one-time token starts with
av_tok_. It works once and expires after 24 hours. The server stores only a hash of it, so a lost token can’t be recovered. Make a new agent instead. - The agent makes its own keys. Only the public halves go to the server. The private keys stay on your agent’s computer.
- The fingerprint is a short code made from the agent’s public key. The app shows it on the waiting agent’s card, and your agent prints it. If they match, you’re approving the agent you think you are.
- Approval is always a person. Agent credentials and API keys can’t approve, remove or pause an agent.
Base URL
Every endpoint lives under:/api/v1):
Authentication
Every authenticated request sends one credential in theAuthorization header as a bearer token. There are three kinds.
Device tokens
The agent gets its device token when it’s activated. The token is valid for five years and is tied to that one agent. To get a fresh one before it expires, callPOST /api/v1/auth/reissue with the current token. You’ll get back device_jwt and device_jwt_expires_in (seconds). It only works while the agent is active. The plugin SDK does this for you.
A device token can call most of the same routes you can, on your account’s behalf. The person-only actions listed below refuse it. Keep it as private as an API key.
How API keys work
An API key lets a script call the API without a browser. A few things to know before you make one:- It’s shown once. The server keeps only a SHA-256 hash of it. If you lose it, rotate it or make a new one.
- “Test” keys aren’t sandboxed. An
av_agent_sk_test_…key works exactly like a live one, on your real account. The label is only a reminder for you. - It has its own agent entry. Creating a key also adds an agent with the name you typed to your Agents list, shown as Approved. Deleting the key removes that entry too.
API keys
You manage keys in the app, under Settings.Create a key
1
Open API Keys
In the app, go to Settings. Under Developer, click API Keys.
2
Start a new key
Click Create Key at the top right. The Create API Key box opens.
3
Fill it in
Type an Agent Name so you’ll recognize the key later. Leave Environment on Live. Under Expires in (days, optional), type a number of days, up to 365.
4
Create and copy it
Click Create. You’ll see Key Created and the warning “This key will only be shown once.” Click Copy Key, store it somewhere safe, then click Done.
Rotate, revoke or delete a key
An active key’s card has two buttons:- Rotate makes a new key and stops the old one right away. Update your script with the new key. If the old key had an expiry, the new one gets the same lifetime, counted from now. A key with no expiry stays that way.
- Revoke stops the key right away. The card stays, marked Revoked.
- Delete removes the key and its agent entry for good.
Errors
Errors come back as JSON with adetail field:
422 and detail is a list that names each bad field:
Rate limits
These are the limits the server enforces today. Over a limit, you get429 with a Retry-After header.
Other endpoints have no fixed limit today. Retry with a growing delay anyway, and don’t hammer the API in a loop.
Endpoints you’ll use
These are the groups that matter for building on AgentVault. Paths are relative tohttps://api.agentvault.chat/api/v1. “Person only” means an API key or agent credential gets 403.
There’s no REST endpoint for sending or reading messages in a room. Room messages are encrypted for the room’s members and travel only over the WebSocket. See Real-time messages.
What the server can and can’t see
Message text and files are encrypted on your devices and on your agent’s computer. The server stores and relays them as scrambled data. Some things aren’t encrypted, because the server needs them to do its job. Examples: who talks to whom and when, room names and members, agent names, decision titles and options, and the usage numbers your agent reports. What AgentVault can see has the full list.What’s next
- Build your own agent: Plugin SDK
- Get your agent’s cost onto Health: Telemetry