feat: As a user, I want to reference a secret in ai-proxy plugin, so that I don't have to write the apikey in plain text in plugin configuration

[mikyll]

Description

Context

Currently, ai-proxy plugin supports auth in 3 ways:

• auth.header - plain text value in plugin config
• auth.query - plain text value in plugin config
• auth.gcp - with JSON auth file with service account in plugin config or ENV var (GCP_SERVICE_ACCOUNT)

Goal/Use Case

I have a Kubernetes deployment (APISIX Ingress Controller) and Secret resources created/updated via an external secret vault service. This allows, for example, to rotate secret values without redeploying APISIX instances.

I'd like to avoid writing the API key value in my plugin's config and use, for example, a reference to the secret resource, similarly to how *-auth plugin works on Consumer, with authParameter (APISIX Ingress Controller Docs | ApisixConsumer).

Proposal

I'd like to discuss the following implementations and understand if and why they can (or cannot) be implemented:

1. Support auth via environment variables reference, similarly to Consumer's *-auth plugins $ENV://$env_name/$sub_key.

   Example usage:

   routes:
     - id: ai_endpoint
       uri: /ai/chat/completions
       plugins:
         ai-proxy:
           provider: openai-compatible
           auth:
             header:
               Authorization: Bearer $ENV://MY_API_TOKEN
           # ...

   For reference: APISIX Docs | Secret - Use environment variables to manage secrets

2. Support auth via some sort of secret reference, e.g. $secret.secret_id:

   routes:
     - id: ai_endpoint
       uri: /ai/chat/completions
       plugins:
         ai-proxy:
           provider: openai-compatible
           auth:
             header:
               Authorization: Bearer $secret.my_secret_id
           # ...

3. Perform context variable resolution on auth parameters (query and header). The token could be fetched and injected via another plugin or something similar:

   routes:
     - id: ai_endpoint
       uri: /ai/chat/completions
       plugins:
         serverless-pre-function:
           phase: rewrite
           functions:
             - |
               return function(conf, ctx)
                 # Some logic to fetch the secret
                 ctx.var.my_secret = "abc123"
               end
         ai-proxy:
           provider: openai-compatible
           auth:
             header:
               Authorization: Bearer $my_secret
           # ...

4. Other? Maybe consumer-based?

I also have another question: why do *-auth plugin support secret resolution via $ENV:// and $secret:// but others do not? Is there a specific design choice?

[Baoyuantop]

Thanks for the detailed proposal! This is a valid use case and the implementation is actually straightforward.

Root Cause

The fetch_secrets mechanism in APISIX already supports recursive secret resolution for any table structure — it handles both $ENV:// and $secret:// prefixes out of the box. The issue is simply that ai-proxy (and ai-proxy-multi) never
calls fetch_secrets before using auth.header / auth.query, unlike similar plugins (e.g. ai-aws-content-moderation, authz-keycloak, openid-connect) which already do this.

The auth.header / auth.query schema accepts arbitrary strings, so $ENV://MY_API_TOKEN or $secret://vault/my-secret/apikey are already valid values syntactically — they just won't be resolved at runtime.

Recommended Fix

Call fetch_secrets(ai_instance.auth, true) in apisix/plugins/ai-proxy/base.lua before constructing extra_opts. This would enable both Proposal 1 and Proposal 2 from your issue with a minimal, localized change. The same fix should be
applied to ai-proxy-multi.

On Proposal 3 (context variable $my_secret): ai-proxy currently performs no ngx.var interpolation on auth fields, so this would require significantly more work and doesn't align with APISIX's established Secret reference conventions —
not recommended.

On Proposal 4 (Consumer-based): technically possible as a workaround today, but not a direct solution for route-level auth in ai-proxy.