Documentation

Basics

Learn the basics of vestauth in just a few minutes.

Agent: Identity & Authentication
Tool: Verification

Agent: Identity & Authentication

Give agents cryptographic identities…

$ mkdir your-agent
$ cd your-agent

$ vestauth agent init
✔ agent created (.env/AGENT_UID=agent-4b94ccd425e939fac5016b6b)

…and sign their curl requests with cryptographic authentication.

> SIGNED - 200
$ vestauth agent curl https://api.vestauth.com/whoami
{"uid":"agent-4b94ccd425e939fac5016b6b",...}

> UNSIGNED - 400
$ curl https://api.vestauth.com/whoami
{"error":{"status":400,"code":null,"message":"bad_request","help":null,"meta":null}}

Tool: Verification

Verify requests and safely trust agent identity using cryptographic proof.

Node

// index.js
const express = require('express')
const vestauth = require('vestauth')
const app = express()

// vestauth agent curl http://localhost:3000/whoami
app.get('/whoami', async (req, res) => {
  try {
    const url = `${req.protocol}://${req.get('host')}${req.originalUrl}`

    // --------------------------------------------------------------------------------
    // 🪪 Reveal the agent's cryptographic identity.                                 //
    // The `tool.verify` method turns your endpoint into a cryptographically     //
    // authenticated tool — verifying signatures, keys, and returning the agent. //
    // --------------------------------------------------------------------------------
    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 }})
  }
})

app.listen(3000, () => { console.log('listening on http://localhost:3000') })

$ npm install express vestauth --save
$ node index.js
listening on http://localhost:3000

$ vestauth agent curl http://localhost:3000/whoami
{"uid":"agent-4b94ccd425e939fac5016b6b",...}