For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Authenticate requests using API keys with configurable validation modes.

Attaches to:

API keyAPI KeyA secret token used to authenticate API requests. Agentgateway can validate API keys and attach metadata to authenticated requests. authenticationAuthentication (AuthN)The process of verifying the identity of a user or service. Agentgateway supports various authentication methods including JWT, API keys, and basic authentication. enables authenticating requests based on a user-provided API key.

Configure API key authentication

API Key authentication involves configuring a list of valid API keys, with associated metadata about the key (optional).

Additionally, authentication can run in three different modes:

• Strict: A valid API key must be present.
• Optional (default): If an API key exists, validate it.
  Warning: This allows requests without an API key!
• Permissive: Requests are never rejected. This setting is useful for usage of claims in later steps such as authorization or logging.
  Warning: This allows requests without an API key!

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
llm:
  policies:
    apiKey:
      mode: strict
      keys:
      - key: sk-testkey-1
        metadata:
          user: test
          role: admin
  models:
  - name: "*"
    provider: openAI
    params:
      apiKey: "$OPENAI_API_KEY"

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
mcp:
  port: 3000
  policies:
    apiKey:
      mode: strict
      keys:
      - key: sk-testkey-1
        metadata:
          user: test
          role: admin
  targets:
  - name: everything
    stdio:
      cmd: npx
      args: ["@modelcontextprotocol/server-everything"]

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
gateways:
  default:
    port: 3000
    apiKey:
      mode: strict
      keys:
      - key: sk-testkey-1
        metadata:
          user: test
          role: admin
routes:
- backends:
  - host: localhost:8080

Later policies can now operate on the metadata associated with the API key. For example, you can set a custom x-authenticated-user header with the authenticated user from the API key metadata by adding a route-level transformation.

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
llm:
  policies:
    apiKey:
      mode: strict
      keys:
      - key: sk-testkey-1
        metadata:
          user: test
          role: admin
    transformations:
      request:
        set:
          x-authenticated-user: apiKey.user
  models:
  - name: "*"
    provider: openAI
    params:
      apiKey: "$OPENAI_API_KEY"

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
mcp:
  port: 3000
  policies:
    apiKey:
      mode: strict
      keys:
      - key: sk-testkey-1
        metadata:
          user: test
          role: admin
    transformations:
      request:
        set:
          x-authenticated-user: apiKey.user
  targets:
  - name: everything
    stdio:
      cmd: npx
      args: ["@modelcontextprotocol/server-everything"]

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
gateways:
  default:
    port: 3000
    apiKey:
      mode: strict
      keys:
      - key: sk-testkey-1
        metadata:
          user: test
          role: admin
routes:
- policies:
    transformations:
      request:
        set:
          x-authenticated-user: apiKey.user
  backends:
  - host: localhost:8080

LLM budgets and model access

An API key entry can carry two fields that apply to LLM traffic. The budgets field sets a per-key budget that caps what the key spends. The allowedModels field limits which models the key can reach. Both fields work with a key entry and with a keyHash entry.

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
config:
  database:
    url: sqlite://budgets.db
llm:
  policies:
    apiKey:
      mode: strict
      keys:
      - key: sk-testkey-1
        metadata:
          name: team-a
          user: test
        allowedModels:
        - "gpt-5*"
        - claude-sonnet-5
        budgets:
        - name: daily-spend
          limit:
            unit: USD
            amount: 50
          window:
            rolling: 24h
          onBudgetExceeded: Block
  models:
  - name: "*"
    provider: openAI
    params:
      apiKey: "$OPENAI_API_KEY"

Two requirements apply to budgets only, and agentgateway refuses to start if either is unmet:

• The configuration must set config.database.url, because agentgateway stores budget counts in a database. Setting config.logging.database.url instead does not satisfy this requirement, because that field configures request logging only. For more information, see Configuration storage.
• Every key that has a budget must set metadata.name, which identifies the key in budget counts, logs, and the admin API.

The allowedModels field has neither requirement, so you can use it without a database.

For a walkthrough that enforces both fields and checks the results, see Per-key dollar or token budgets.