Skip to main content
A Service is a per-vault configuration that defines which hosts agents can reach through the proxy and how Agent Vault authenticates to each one. When an agent makes a proxied request, Agent Vault matches the target host against the vault’s services, attaches the configured credentials, and forwards the request. If no service matches, Agent Vault returns 403. Each service contains:
  • Host: The target hostname. Supports exact match (e.g. api.stripe.com) or wildcard patterns (e.g. *.github.com).
  • Auth config: How Agent Vault authenticates to the host. Five types are supported: bearer, basic, api-key, custom, and passthrough (opt out of injection).
  • Description: An optional human-readable label shown in /discover responses.
The /discover endpoint returns the list of hosts and descriptions from the vault’s services. Agents use this to know which services are already available before raising a proposal.
Similar to credentials, services can be configured in two ways:
  • Automatically: As agents do their work, they can raise proposals to add or modify services. You review each proposal, provide any required credentials, and approve. This is the recommended workflow for working with Agent Vault.
  • Manually: You can set services directly via the CLI by applying a YAML file or by using the interactive builder. This can be useful for pre-configuring a vault before inviting agents.

​
Service structure

Services are defined in a YAML file. Here’s what a single service looks like:
stripe-services.yaml
services:
  - host: api.stripe.com
    description: Stripe API
    auth:
      type: bearer
      token: STRIPE_KEY

agent-vault vault service set -f stripe-services.yaml --vault my-vault
The host tells Agent Vault which requests this service applies to. The auth block tells Agent Vault how to authenticate, referencing credential keys by name (not the actual credential values). The following section covers all five auth types.

​
Auth types

Every service must include an auth config that tells Agent Vault how to authenticate to the target host. The auth config references credential key names (not the actual credential values) stored in the vault.

​
Bearer

Attaches an Authorization: Bearer <token> header. The token field references a credential key. 
services:
  - host: api.stripe.com
    description: Stripe API
    auth:
      type: bearer
      token: STRIPE_KEY
Common services: Stripe, GitHub, OpenAI.

​
Basic

Attaches an Authorization: Basic <base64> header using HTTP Basic authentication. The username field is required; password is optional (defaults to empty). 
services:
  - host: api.ashbyhq.com
    description: Ashby ATS API
    auth:
      type: basic
      username: ASHBY_API_KEY
With a password: 
services:
  - host: yoursite.atlassian.net
    description: Jira API
    auth:
      type: basic
      username: JIRA_EMAIL
      password: JIRA_API_TOKEN

​
API key

Attaches a credential value to a named header with an optional prefix. The header field defaults to Authorization if omitted. 
services:
  - host: api.anthropic.com
    description: Anthropic API
    auth:
      type: api-key
      key: ANTHROPIC_KEY
      header: x-api-key
With a prefix: 
services:
  - host: api.example.com
    auth:
      type: api-key
      key: EXAMPLE_KEY
      header: Authorization
      prefix: "ApiKey "

​
Custom

Freeform header templates with {{ SECRET }} placeholders. Each placeholder is resolved to the corresponding credential at proxy time. Use this when none of the typed auth methods fit. 
services:
  - host: api.acme.internal
    description: Internal ACME service
    auth:
      type: custom
      headers:
        X-API-Key: "{{ ACME_API_KEY }}"
        X-Tenant-ID: "{{ ACME_TENANT }}"

​
Passthrough

Allowlists the host without injecting a credential. The client’s request headers (including Authorization and Cookie) flow through to the target unchanged; Agent Vault strips only hop-by-hop headers and broker-scoped headers (X-Vault, Proxy-Authorization). No credential is stored, read, or attached. 
services:
  - host: api.example.com
    description: Client already holds the credential
    auth:
      type: passthrough
Use passthrough when the operator has decided their client already holds the credential (for example, an existing tool that manages its own token) and wants Agent Vault to provide the host allowlist, netguard, TLS interception, and audit logging without putting the secret in the vault. All the other auth types are the default — reach for passthrough only when you explicitly want Agent Vault not to broker the credential.
Passthrough auth configs reject every credential field (token, username, password, key, header, prefix, headers). Setting any of them returns a validation error — if you want Agent Vault to inject a credential, use one of the credentialed auth types instead.
Every credential key referenced in an auth config (whether directly or via {{ KEY }} templates) must resolve to either an existing credential in the vault or a credential slot in the same proposal. Agent Vault returns 400 if a key is missing. This does not apply to passthrough services, which reference no credentials.

​
Host matching

Agent Vault supports two host matching modes:
  • Exact match: api.stripe.com matches only api.stripe.com.
  • Wildcard: *.github.com matches api.github.com, uploads.github.com, etc. The * replaces exactly one subdomain segment.

​
Example

A vault can define multiple services with different auth types:
services.yaml
services:
  - host: api.stripe.com
    description: Stripe API
    auth:
      type: bearer
      token: STRIPE_KEY

  - host: "*.github.com"
    description: GitHub API
    auth:
      type: bearer
      token: GITHUB_TOKEN

  - host: api.anthropic.com
    description: Anthropic API
    auth:
      type: api-key
      key: ANTHROPIC_KEY
      header: x-api-key

  - host: yoursite.atlassian.net
    description: Jira API
    auth:
      type: basic
      username: JIRA_EMAIL
      password: JIRA_API_TOKEN

agent-vault vault service set -f services.yaml --vault my-vault
Any agent scoped to the vault named my-vault can now proxy requests to these hosts, and Agent Vault attaches the real credentials at request time.

​
Managing services

​
Set from a file

agent-vault vault service set -f services.yaml --vault my-vault
Replaces the entire service configuration with the contents of the file. This is idempotent, running it twice with the same file produces the same result.

​
Set interactively

agent-vault vault service set --vault my-vault
Walks you through adding services, auth configs, and credential references one at a time. Requires a TTY (won’t work in scripts).

​
View current services

agent-vault vault service list --vault my-vault
Prints the active services as YAML. If no services are configured, the output is empty.

​
Clear all services

agent-vault vault service clear --vault my-vault
Removes all services. Agents scoped to this vault will get 403 on every proxy request until new services are configured. Prompts for confirmation unless you pass --yes.
The --vault flag defaults to default on all service commands. You only need to specify it when working with additional vaults.
Agents don’t edit service configurations directly. Instead, they propose changes through proposals, bundles of service and credential modifications that a human reviews and approves.Each service in a proposal has an action field:
  • set: Idempotent upsert. Adds the service if the host doesn’t exist, or replaces the existing service for that host. Requires host and auth.
  • delete: Removes the service matching the given host. Only requires host.
When you approve a proposal, Agent Vault atomically merges all service changes into the vault’s configuration in a single transaction. Set services are upserted by host, delete services remove matching entries.This means agents can request access to new services without you manually editing YAML files. You just review and click “Allow” in the browser approval page.
When a proxy request targets a host not covered by any service, Agent Vault returns 403 with a proposal_hint in the response body. The hint includes the denied host and the endpoint to create a proposal.Well-behaved agents use this hint to automatically raise a proposal requesting access. You receive a browser link to review the request and provide any needed credentials.