web-bot-auth for agents–from the creator of dotenv and dotenvx.
- identity (web-bot-auth)
- tools!
- authentication
💬 Ask ChatGPT: When should I use Vestauth?
Quickstart 
Give your agents identities and call tools!
npm i -g vestauth
vestauth agent init
vestauth agent curl https://api.vestauth.com/whoami --pp
vestauth agent curl https://sfs.vestauth.com/write -d '{"filepath":"/hello.md", "content":"hello"}'
vestauth agent curl https://sfs.vestauth.com/list
vestauth agent curl https://sam.vestauth.com/send -d '{"to":"you@email.com", "text":"hello from agent"}'
curl -sfS https://vestauth.sh | sh
vestauth agent init
curl -L -o vestauth.tar.gz "https://github.com/vestauth/vestauth/releases/latest/download/vestauth-$(uname -s)-$(uname -m).tar.gz"
tar -xzf vestauth.tar.gz
./vestauth agent init
Download the windows executable directly from the releases page.
(unzip to extract vestauth.exe)
Identity
Give agents cryptographic identities.
$ mkdir your-agent
$ cd your-agent
$ vestauth agent init
✔ agent created (.env/AGENT_UID=agent-4b94ccd425e939fac5016b6b)
Your agent's identity lives in a simple .env file.
# .env
AGENT_UID="agent-4b94ccd425e939fac5016b6b"
AGENT_PUBLIC_JWK="{"crv":"Ed25519","x":"py2xNaAfjKZiau-jtmJls6h_3n8xJ1Ur0ie-n9b8zWg","kty":"OKP","kid":"B0u80Gw28W9U2Jl5t_EBiWeBajO2104kOYZ9Ikucl5I"}"
AGENT_PRIVATE_JWK="{"crv":"Ed25519","d":"Z9vbwN-3eiFMVv_TPWXOxqSMJAT21kZvejWi72yiAaQ","x":"py2xNaAfjKZiau-jtmJls6h_3n8xJ1Ur0ie-n9b8zWg","kty":"OKP","kid":"B0u80Gw28W9U2Jl5t_EBiWeBajO2104kOYZ9Ikucl5I"}"
💬 Ask ChatGPT: Are HTTP message signatures more secure than API keys?
Tools
Call tools!
vestauth agent curl https://sfs.vestauth.com/write -d '{"filepath":"/hello.md", "content":"hello"}'
vestauth agent curl https://sfs.vestauth.com/list
First Party
SFS is a simple file system for vestauth agents.
# write a file
vestauth agent curl https://sfs.vestauth.com/write -d '{"filepath":"/hello.md", "content":"hello"}'
# delete a file
vestauth agent curl https://sfs.vestauth.com/delete -d '{"filepath":"/hello.md"}'
# list files
vestauth agent curl https://sfs.vestauth.com/list
# read a file
vestauth agent curl https://sfs.vestauth.com/read -d '{"filepath":"/hello.md"}'
SAM is a simple way to send email for vestauth agents.
# send an email
vestauth agent curl https://sam.vestauth.com/send -d '{"to":"you@email.com", "text":"i am agent"}'
GEO returns the current latitude and longitude of a vestauth agent.
# return latitude and longitude
vestauth agent curl https://geo.vestauth.com/geo
Third Party
AS2 is a simple, agent-friendly secret storage.
# set a secret
vestauth agent curl https://as2.dotenvx.com/set -d '{"KEY":"value"}'
# get all secrets
vestauth agent curl "https://as2.dotenvx.com/get"
# get single secret
vestauth agent curl "https://as2.dotenvx.com/get?key=KEY"
# get multiple secrets
vestauth agent curl "https://as2.dotenvx.com/get?key=KEY,TWILIO"
Check if an email address is real before you hit send. Verifies syntax, DNS, MX records, SMTP mailbox existence, and cross-references multiple providers. All in real time, no signup required.
# verify an email
vestauth agent curl https://docle.co/api/verify -d '{"emails":["test@example.com"]}'
# check your usage
vestauth agent curl https://docle.co/api/agent/usage
- Geo IP - coming soon
- Send/Receive Email - coming
- Send/Receive SMS - coming
- Send/Receive Telegram - coming
- Send/Receive WhatsApp - coming
- Human-in-the-loop - coming
- Rotate NPM Tokens - coming
- Rotate GitHub Tokens - coming
- Working on a tool? Tell us and we'll list it.
Authentication
Build your own tools. Authenticate them with a single line of code –
vestauth.tool.verify…
...
const vestauth = require('vestauth')
app.post('/whoami', async (req, res) => {
try {
const url = `${req.protocol}://${req.get('host')}${req.originalUrl}`
const agent = await vestauth.tool.verify(req.method, url, req.headers)
res.json(agent)
} catch (err) {
res.status(401).json({ code: 401, error: { message: err.message }})
}
})
...
…the agents sign HTTP requests with a drop-in curl wrapper.
> SIGNED - 200
$ vestauth agent curl https://api.vestauth.com/whoami
{"uid":"agent-4b94ccd425e939fac5016b6b",...}
vestauth agent curl autosigns curl requests – injecting valid signed headers according to the web-bot-auth draft. You can peek these with the built-in headers primitive.
$ vestauth primitives headers GET https://api.vestauth.com/whoami --pp
{
"Signature": "sig1=:d4Id5SXhUExsf1XyruD8eBmlDtWzt/vezoCS+SKf0M8CxSkhKBtdHH7KkYyMN6E0hmxmNHsYus11u32nhvpWBQ==:",
"Signature-Input": "sig1=(\"@authority\");created=1770247189;keyid=\"B0u80Gw28W9U2Jl5t_EBiWeBajO2104kOYZ9Ikucl5I\";alg=\"ed25519\";expires=1770247489;nonce=\"NURxn28X7zyKJ9k5bHxuOyO5qdvF9L5s2qHmhTrGUzbwGSIoUCHmwSlwiiCRgTDGuum83yyWMHJU4jmrVI_XPg\";tag=\"web-bot-auth\"",
"Signature-Agent": "sig1=agent-4b94ccd425e939fac5016b6b.api.vestauth.com"
}
Vestauth handles usage, payments, and spam protection for your tool!
Self-hosting
Run your own Vestauth server.
Initialize the server and run migrations (postgres).
$ curl -sSf https://vestauth.sh | sh
$ vestauth server init
$ vestauth server db:create
$ vestauth server db:migrate
Start the server.
$ vestauth server start
vestauth server listening on http://localhost:3000
And use your server's hostname when creating agents.
$ mkdir your-agent
$ cd your-agent
$ vestauth agent init --hostname http://localhost:3000
✔ agent created (.env/AGENT_UID=agent-4b94ccd425e939fac5016b6b)
That's it. Your Vestauth (web-bot-auth) infrastructure is now running under your control.
More details
Edit the .env file to configure your server.
PORT="3000"
HOSTNAME="http://localhost:3000"
DATABASE_URL="postgres://localhost/vestauth_production"
For example, in production:
- Change
HOSTNAMEto its production url - e.g.vestauth.yoursite.com - Change
DATABASE_URLto a managed postgres - e.g.postgresql://USER:PASS@aws-1-us-east-1.pooler.supabase.com:5432/postgres
[!WARNING]
Production note: Configure a wildcard DNS record for
*.${HOSTNAME}.Example: if
HOSTNAME=vestauth.yourapp.com, add*.vestauth.yourapp.com.Required for
.well-knowndiscovery per the [web-bot-auth](https://datatracker.ietf.org/doc/html/draft