Skip to main content

Securing Your Agent's API

Securing your API with AgentVisor™ involves two complementary layers: transport security (TLS) encrypts all traffic between clients and the API, while authentication establishes who is making each request. Both are optional during local development but essential for production deployments.

You've been using the anonymous principal throughout these tutorials — policies evaluated that principal to make allow/deny decisions. This chapter shows you how to add TLS encryption and configure real identities via OIDC.

What You'll Learn​

  • How TLS encrypts traffic between clients and the API
  • How authentication establishes identity for policy evaluation
  • Development options for both TLS and identity testing
  • Configuring TLS and OIDC for production deployments

Enabling TLS​

TLS (Transport Layer Security) is available as an option to encrypt all traffic between clients and your API, preventing eavesdropping and tampering.

Development: Auto-Generated Certificates​

For local development, AgentVisor can generate a self-signed certificate automatically:

# agentvisor.yaml
api:
  listen_addr: ":8443"
  tls:
    enabled: true
    auto_cert: true
Development Only

Auto-generated certificates are self-signed and not trusted by clients. Only use auto_cert: true for local development. Production deployments must use certificates from a trusted Certificate Authority.

Test the connection with curl (use -k to skip certificate verification for self-signed certs):

curl -k https://localhost:8443/health

Production: Using Real Certificates​

For production, provide certificates from a trusted Certificate Authority:

# agentvisor.yaml
api:
  listen_addr: ":8443"
  tls:
    enabled: true
    cert_file: "/etc/agentvisor/tls/server.crt"
    key_file: "/etc/agentvisor/tls/server.key"

Common certificate sources include:

  • Let's Encrypt / ACME: Free, automated certificates
  • Internal PKI: Corporate Certificate Authority
  • Cloud providers: AWS ACM, Google-managed certificates, Azure Key Vault

Alternatively, you can terminate TLS externally using an ingress controller or load balancer, allowing AgentVisor to run with plaintext HTTP behind the proxy.

Optional: Mutual TLS (mTLS)

For environments requiring client certificate authentication, AgentVisor supports mTLS. This advanced configuration requires clients to present valid certificates. See the Configuration Reference for client_ca_file and client_auth options.

Understanding Authentication​

Authentication establishes who is making a request (the principal). Authorization — which you learned in Adding Policies — decides what that principal is allowed to do. They work together:

Authentication extracts an identity from the request (e.g., a JWT token), and that identity's claims become the principal used in policy evaluation. For example, an OIDC JWT's sub claim becomes principal.sub in your policy rules.

See Policy Enforcement for the full picture of how these pieces fit together.

Development Identity Options​

AgentVisor provides several ways to test policies with different identities during development:

warning

These options are for local development only. Always configure proper authentication for production deployments.

Anonymous Principal (default)​

With API auth disabled (the default), every request uses the anonymous principal:

{
  "sub": "anonymous",
  "mroles": ["mrn:agentvisor:role:anonymous"]
}

Your policies can grant access to this role for development — which is what we did in Adding Policies.

Simulate a Principal with --principal-file​

--principal-file is available on agentvisor run (a single agent invocation that exits when done), not agentvisor serve. It's useful for checking how a specific identity's claims evaluate against your policies before wiring up real authentication:

# principal.json
# {"sub": "alice", "mroles": ["mrn:agentvisor:role:admin"]}

agentvisor run ./my-agent --principal-file ./principal.json --input '{"messages": [{"role": "user", "content": "Hello!"}]}'

The run executes once as alice and prints its result (Output on success, Error on policy denial) to the console.

Per-Request Identity with X-Test-Principal​

For a running agentvisor serve instance, test mode lets you inject a different principal per request instead of always using the anonymous principal:

# Enable test mode
AGENTVISOR_API_AUTH_TEST_MODE=true agentvisor serve ./my-agent
# Test as different users
curl -H 'X-Test-Principal: {"sub": "alice"}' -X POST http://localhost:8090/threads

curl -H 'X-Test-Principal: {"sub": "bob"}' -X POST http://localhost:8090/threads
mroles Cannot Be Forged

The authenticator strips any mroles claim from the X-Test-Principal header before building the principal (logging a warning when it does) — without this, anyone who could enable test mode could mint an admin-equivalent principal just by naming the role in the header. This means the header is only useful for testing policy rules keyed on sub or other identity claims. To test mroles-based (role) policy rules, use --principal-file above, or configure real OIDC authentication.

Authorization Bypass​

Skip all policy evaluation entirely when debugging agent logic:

AGENTVISOR_AUTHZ_TYPE=allowall agentvisor serve ./my-agent

Production Authentication: OIDC​

For production, configure OIDC (OpenID Connect) so each request carries a verified JWT:

# agentvisor.yaml
api:
  auth:
    enabled: true
    oidc_issuer: "https://accounts.google.com"
    oidc_audience: "your-client-id.apps.googleusercontent.com"

AgentVisor validates the JWT signature, checks expiration, and extracts claims to build the principal. Your existing policies then evaluate against the real identity — no policy changes needed — real identities instead of anonymous.

tip

For complete API security, enable both TLS and OIDC authentication in production.

Next Steps​