Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/vestauth/vestauth/llms.txt

Use this file to discover all available pages before exploring further.

​
Installation

Install Vestauth as a dependency in your Node.js project:
npm
npm install vestauth
yarn
yarn add vestauth
pnpm
pnpm add vestauth

​
Quick Start

Vestauth provides three main APIs for different use cases:

​
Agent API

For creating and managing agent identities: 
const vestauth = require('vestauth')

// Initialize a new agent
const result = await vestauth.agent.init()
console.log(result.AGENT_UID) // agent-4b94ccd425e939fac5016b6b

// Generate signed headers for a request
const headers = await vestauth.agent.headers('GET', 'https://api.example.com/data')

​
Tool API

For verifying agent requests in your tools: 
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 }})
  }
})

​
Primitives API

For low-level cryptographic operations: 
const vestauth = require('vestauth')

// Generate a new Ed25519 keypair
const kp = vestauth.primitives.keypair()
console.log(kp.publicJwk)
console.log(kp.privateJwk)

// Sign headers with specific credentials
const headers = await vestauth.primitives.headers(
  'POST',
  'https://api.example.com/data',
  'agent-123',
  JSON.stringify(privateJwk)
)

​
Import Styles

const vestauth = require('vestauth')

// Access APIs
vestauth.agent.init()
vestauth.tool.verify()
vestauth.primitives.keypair()

​
API Reference

Agent API

Create agents, generate signatures, rotate keys

Tool API

Verify and authenticate agent requests

Primitives API

Low-level cryptographic operations

Server API

Self-host Vestauth infrastructure

​
TypeScript Support

Vestauth includes TypeScript type definitions. No additional @types package is needed: 
import vestauth from 'vestauth'
import type { PublicJwk, PrivateJwk, SignatureHeaders, VerifyResult } from 'vestauth'

const headers: SignatureHeaders = await vestauth.agent.headers(
  'GET',
  'https://api.example.com/data'
)

const result: VerifyResult = await vestauth.tool.verify(
  'POST',
  url,
  requestHeaders
)

​
Environment Variables

Vestauth reads agent credentials from environment variables (typically stored in .env):
.env
AGENT_UID="agent-4b94ccd425e939fac5016b6b"
AGENT_PUBLIC_JWK='{"crv":"Ed25519","x":"py2xNaAfjKZiau...","kty":"OKP","kid":"B0u80Gw28W9U2Jl5t..."}'
AGENT_PRIVATE_JWK='{"crv":"Ed25519","d":"Z9vbwN-3eiFMVv_TPWXOxqSM...","x":"py2xNaAfjKZiau...","kty":"OKP","kid":"B0u80Gw28W9U2Jl5t..."}'
AGENT_HOSTNAME="https://api.vestauth.com"
Use vestauth.agent.init() to automatically generate and save these credentials.

​
Standards Compliance

Vestauth implements:
  • RFC 9421 - HTTP Message Signatures
  • Web-Bot-Auth Draft - Agent authentication architecture
  • Ed25519 - Modern elliptic curve cryptography
  • JWK (RFC 7517) - JSON Web Key format

​
Error Handling

All async methods throw errors on failure. Wrap calls in try-catch blocks: 
try {
  const agent = await vestauth.tool.verify(method, url, headers)
  console.log('Verified agent:', agent.uid)
} catch (error) {
  if (error.message.includes('expired')) {
    console.error('Signature has expired')
  } else if (error.message.includes('invalid')) {
    console.error('Invalid signature')
  } else {
    console.error('Verification failed:', error.message)
  }
}

​
Next Steps

Agent API

Learn how to create and manage agents

Tool API

Build tools that authenticate agents

Build docs developers (and LLMs) love

Get started for freeTalk to us