> ## 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.

# Frequently Asked Questions

> Common questions about Vestauth authentication for agents

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="What problem does Vestauth solve?">
    Vestauth gives agents a cryptographic identity and a simple way to authenticate HTTP requests.

    Most agent systems rely on API keys, bearer tokens, or username/passwords. These approaches are difficult to rotate, easy to leak, and hard to attribute to a specific agent.

    Vestauth replaces shared secrets with public/private key cryptography. Agents sign requests using a private key, and tools verify those requests using the agent's public key.
  </Accordion>

  <Accordion title="Is there a demo video?">
    Yes

    [Watch the demo](https://www.youtube.com/watch?v=cHARyULr_qk)
  </Accordion>

  <Accordion title="Why not just use API keys?">
    API keys are shared secrets. Anyone who obtains the key can impersonate the client, and keys are difficult to rotate safely.

    Vestauth uses cryptographic signing instead of shared secrets. This allows tools to verify identity without storing or distributing sensitive credentials.
  </Accordion>

  <Accordion title="Where are agent keys stored?">
    Agent keys are generated locally and stored in the agent's environment configuration (`.env`).

    * `AGENT_PRIVATE_JWK` is used to sign requests and must never be shared.
    * `AGENT_PUBLIC_JWK` is safe to publish and is used by tools for verification.
  </Accordion>

  <Accordion title="Is Vestauth only for AI agents?">
    No.

    Vestauth can authenticate any automated system including:

    * developer tools
    * CLIs
    * automation services
    * bots
    * infrastructure tools
  </Accordion>

  <Accordion title="Can Vestauth work without curl?">
    Yes.

    Vestauth provides libraries and primitives that can be integrated into any HTTP client or framework. The CLI simply makes it easy to adopt and demonstrate.
  </Accordion>

  <Accordion title="Do I need to run a Vestauth server?">
    No.

    Vestauth is primarily a client-side and verification library. Agents generate keys locally and sign requests directly. Tools verify requests using public keys exposed via .well-known discovery endpoints.

    There is no central authentication server required.
  </Accordion>

  <Accordion title="Can I host my own Vestauth server?">
    Yes.

    To host your own Vestauth server create the database, run the migrations, and start the server.

    ```bash theme={null}
    vestauth server db:create
    vestauth server db:migrate
    vestauth server start
    # vestauth server listening on http://localhost:3000
    ```
  </Accordion>

  <Accordion title="Why does Vestauth use Ed25519 keys?">
    Ed25519 provides:

    * Strong modern cryptographic security
    * Fast signing and verification
    * Small key sizes
    * Wide ecosystem support
  </Accordion>

  <Accordion title="How does Vestauth authentication work?">
    Vestauth uses HTTP Message Signatures ([RFC 9421](https://datatracker.ietf.org/doc/rfc9421/)). Each request is signed using the agent's private key. The request includes signed headers such as:

    * Signature
    * Signature-Input
    * Signature-Agent

    Tools verify the request by retrieving the agent's public key from a discovery endpoint and verifying the signature cryptographically.

    If the signature is valid, the tool knows the request was created by the agent that owns that private key.
  </Accordion>

  <Accordion title="How does Vestauth prevent replay attacks?">
    Vestauth prevents replay attacks using multiple mechanisms built into HTTP Message Signatures.

    Each signed request includes:

    * **created timestamp** - limits how old a signature can be
    * **expires timestamp** - defines a short validity window
    * **nonce value** - ensures each request is unique

    Tools verify that:

    1. The signature is still within the allowed time window
    2. The nonce has not been used before
    3. The signature cryptographically matches the request

    Because signatures are short-lived and tied to unique nonce values, an intercepted request cannot be reused successfully.

    Tools may optionally store nonce values for additional replay protection.
  </Accordion>

  <Accordion title="Why does Vestauth use public key discovery?">
    Public key discovery allows tools to verify agent signatures without manual key exchange. Each agent hosts its public keys in a standardized .well-known directory.

    This enables dynamic agent onboarding while preserving cryptographic verification.
  </Accordion>

  <Accordion title="Does Vestauth send secrets over the network?">
    No.

    Vestauth signs requests using private keys locally. Only public keys are shared for verification.
  </Accordion>

  <Accordion title="How does Vestauth avoid SSRF during public key discovery?">
    Vestauth prevents Server-Side Request Forgery (SSRF) by restricting public key discovery to trusted domains.

    By default, Vestauth only resolves agent discovery endpoints inside the controlled namespace:

    ```
    *.api.vestauth.com
    ```

    When a tool verifies a request, Vestauth converts the agent identity into a fixed .well-known endpoint within this trusted domain. Because this domain is controlled by Vestauth, tools never fetch attacker-supplied URLs or internal network addresses.

    This removes the most common SSRF attack vector during signature verification.

    ### Custom trusted discovery domains

    Tools can optionally configure additional trusted discovery domains using:

    ```
    TOOL_FQDN_REGEX
    ```

    This allows organizations to:

    * Host their own agent discovery infrastructure
    * Support private internal agents
    * Implement federated trust models

    For example:

    ```
    TOOL_FQDN_REGEX=".*\\.agents\\.vestauth\\.com|.*\\.agents\\.example\\.internal"
    ```

    Only discovery endpoints matching this allowlist will be fetched.

    ### Defense in depth

    Even with domain scoping, tools may optionally add safeguards such as:

    * HTTPS-only enforcement
    * Request timeouts
    * Response size limits
    * Public key caching

    Vestauth removes SSRF by design, while still allowing controlled federation when needed.
  </Accordion>

  <Accordion title="Why does Vestauth use .well-known discovery instead of embedding public keys directly?">
    Vestauth uses .well-known discovery to keep requests small, enable key rotation, and support long-term identity management.

    Embedding public keys directly in every request would increase header size, reduce caching opportunities, and make key rotation difficult. By publishing keys through a discovery endpoint, Vestauth allows tools to fetch and cache keys independently from individual requests.

    This approach provides several benefits:

    ### Efficient requests

    Public keys are retrieved once and can be cached by tools. Agents do not need to send large key material with every request.

    ### Key rotation support

    Agents can rotate signing keys without changing their identity. Tools simply refresh keys from the discovery endpoint.

    ### Multi-key support

    Agents can safely publish multiple active keys (for rotation or staged rollouts) using the standard HTTP Message Signatures directory format.

    ### Standards alignment

    Vestauth follows the discovery model used in:

    * HTTP Message Signatures directories
    * OAuth / OpenID Connect key discovery
    * Web identity federation systems
  </Accordion>
</AccordionGroup>