Services

Define which services your agents can access and how credentials are attached.

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. No credential is stored, read, or attached; client request headers (including Authorization and Cookie) flow through to the upstream — same as for credentialed services, just without a broker-injected auth header on top.

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.

Header forwarding

Agent Vault forwards your client’s request headers to the upstream unchanged, except for:

• Hop-by-hop headers per RFC 7230 (Connection, Keep-Alive, Proxy-Authenticate, Proxy-Authorization, Proxy-Connection, Te, Trailer, Transfer-Encoding, Upgrade).
• Broker-scoped headers that authenticate the client to Agent Vault itself (X-Vault, Proxy-Authorization).
• The auth slot — the specific header(s) the configured auth type manages. With auth.type: bearer or basic, the broker overrides Authorization. With api-key, it overrides whatever you named in auth.header. With custom, it overrides every key in auth.headers. With passthrough, nothing.

This means vendor headers like anthropic-version, OpenAI-Beta, If-Match, and tracing IDs reach the upstream regardless of auth type. The broker only takes over the headers it’s responsible for injecting.

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.

Substitutions

Auth types only inject HTTP headers. Some upstream APIs want a credential value in the URL path or query string instead — Twilio’s /Accounts/{AccountSID}/Messages.json, legacy services that take ?api_key=. For those, declare a substitutions block alongside the auth.

services:
  - host: api.twilio.com
    description: Twilio Messaging API
    auth:
      type: basic
      username: TWILIO_ACCOUNT_SID
      password: TWILIO_AUTH_TOKEN
    substitutions:
      - key: TWILIO_ACCOUNT_SID
        placeholder: __account_sid__
        in: [path]

The agent then sends GET https://api.twilio.com/2010-04-01/Accounts/__account_sid__/Messages.json (via the explicit /proxy/... ingress or HTTPS_PROXY). Agent Vault:

1. Resolves the basic auth credentials and injects Authorization: Basic <base64(SID:TOKEN)>.
2. Scans only the path (the only surface in in:), finds __account_sid__, replaces it with the URL-encoded SID.
3. Forwards the request.

Field reference

• key — UPPER_SNAKE_CASE credential reference. Must resolve to a credential in the vault or a slot in the same proposal.
• placeholder — the exact wire string Agent Vault matches case-sensitively as a literal. Operators choose the string; the broker does not auto-wrap delimiters around it. The recommended convention is __name__ (double-underscore-bounded snake_case).
• in — list of surfaces the broker is allowed to scan. Subset of path, query, header. Defaults to [path, query] if omitted. body is reserved for a future version.

Scoping is the security boundary

Agent Vault only scans surfaces listed in in. If an agent embeds the placeholder in a non-declared surface (a JSON body to round-trip via an echo upstream, a header that wasn’t declared), the literal string passes through to upstream — the broker will not substitute. There is no way to coerce the broker into substituting somewhere the operator did not authorize.

Use this property to pick a narrow in for strong secrets that happen to live in URLs (legacy ?api_key= APIs): keep in: [query] and the agent cannot exfiltrate the value through a body or a different header.

Placeholder safety rules

The validator rejects placeholders that would cause false-positive substitutions in legitimate URL content:

• Length ≥ 4 characters.
• Must contain a __ sequence or a non-[A-Za-z0-9_] character — so a bare word like account_sid is rejected (it could appear as a real path segment), while __account_sid__, sid.value, sid-val, and ~sid~ all pass.
• At least one alphanumeric character — strings made entirely of delimiters like ____ or ~~~~ are rejected because they would aggressively match URL punctuation.
• Only RFC 3986 unreserved characters [A-Za-z0-9_-.~] are permitted, so the placeholder survives any HTTP client / SDK / middlebox without percent-encoding round-trips.

header scope is request-wide

When in includes header, the broker scans every outbound header for the placeholder — not one specific named header. Pick a unique placeholder so a typo or a copy-pasted value can’t accidentally land in a header you didn’t intend to rewrite. (Path and query are scoped to those URL components and don’t have this concern.)

Composes with all auth types

Substitutions and auth are independent. A service can use either, both, or neither:

• Twilio: auth: basic (header) + path substitution for the SID.
• Legacy ?api_key= API: auth: api-key for an audit header + query substitution for the actual key.
• A pure-substitution case (e.g. an internal API where the only secret lives in the path): auth: passthrough + path substitution.

Modifying substitutions requires re-supplying auth in the same proposal. Auth-only or enable/disable-only set proposals preserve existing substitutions; to clear them, delete and recreate the service.

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.

How proposals modify services

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.

What happens when an agent hits an unknown host

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.