fix(passthrough): OTLP route/identity attribution, route on rejected events, header_key 401 names its header

crates/aisix-core/src/models/passthrough_route.rs

@@ -379,6 +379,30 @@ pub fn passthrough_route_coupling() -> Value {
  }
  }
  },
+ // Cross-mode leftovers are configuration errors, not ignored
+ // fields: a companion outside its mode is never consulted, so a
+ // row carrying one is rejected rather than half-honored. The CP
+ // enforces the identical rule on create and patch.
+ {
+ "title": "auth_header_name only in header_key mode",
+ "if": {
+ "anyOf": [
+ { "title": "auth_mode omitted (defaults to gateway_key)", "not": { "required": ["auth_mode"] } },
+ { "title": "auth_mode: gateway_key or anonymous", "properties": { "auth_mode": { "enum": ["gateway_key", "anonymous"] } }, "required": ["auth_mode"] }
+ ]
+ },
+ "then": { "not": { "required": ["auth_header_name"] } }
+ },
+ {
+ "title": "anonymous_key_id only in anonymous mode",
+ "if": {
+ "anyOf": [
+ { "title": "auth_mode omitted (defaults to gateway_key)", "not": { "required": ["auth_mode"] } },
+ { "title": "auth_mode: gateway_key or header_key", "properties": { "auth_mode": { "enum": ["gateway_key", "header_key"] } }, "required": ["auth_mode"] }
+ ]
+ },
+ "then": { "not": { "required": ["anonymous_key_id"] } }
+ },
  // credential_mode couplings: inject needs a real ProviderKey id; a
  // forward_client route carrying one is a configuration error, not
  // an ignored field.
@@ -516,6 +540,39 @@ mod coupling_tests {
  assert!(validate_passthrough_route(&doc).is_err());
  }
 
+ #[test]
+ fn cross_mode_leftover_companions_are_rejected() {
+ // A companion outside its mode is never consulted at runtime, so
+ // both validators refuse the row instead of half-honoring it.
+ // auth_header_name without header_key (auth_mode absent = gateway_key).
+ let mut doc = base();
+ doc["auth_header_name"] = json!("x-aisix-api-key");
+ assert!(validate_passthrough_route(&doc).is_err());
+ assert!(validate_passthrough_route_lenient(&doc).is_err());
+ // anonymous_key_id on an explicit header_key route.
+ let doc = json!({
+ "name": "r", "path_prefix": "/p",
+ "target_url": "https://u.example", "provider_key_id": "pk",
+ "auth_mode": "header_key", "auth_header_name": "x-aisix-api-key",
+ "anonymous_key_id": "ak-1"
+ });
+ assert!(validate_passthrough_route(&doc).is_err());
+ // auth_header_name on an anonymous route.
+ let doc = json!({
+ "name": "r", "path_prefix": "/p",
+ "target_url": "https://u.example", "provider_key_id": "pk",
+ "auth_mode": "anonymous", "anonymous_key_id": "ak-1",
+ "source_cidrs": ["10.0.0.0/8"],
+ "auth_header_name": "x-aisix-api-key"
+ });
+ assert!(validate_passthrough_route(&doc).is_err());
+ // source_cidrs is deliberately NOT mode-coupled: an extra IP
+ // allowlist is honored on every mode.
+ let mut doc = base();
+ doc["source_cidrs"] = json!(["10.0.0.0/8"]);
+ assert!(validate_passthrough_route(&doc).is_ok());
+ }
+
  #[test]
  fn credential_bearing_header_slots_are_rejected() {
  for field in ["auth_header_name", "identity_header"] {

crates/aisix-obs/src/otlp_http_sink.rs

@@ -743,6 +743,16 @@ fn build_otlp_span(record: &SinkRecord, exporter_name: &str) -> Value {
  &event.client_user_agent,
  ));
  }
+ // End-user identity a passthrough route's `identity_header` extracted —
+ // the per-employee attribution of the forward-proxy scenario. Not gated
+ // on the protocol so a future handler that learns to populate it exports
+ // it without touching this sink.
+ if !event.client_identity.is_empty() {
+ attributes.push(attr_string_capped(
+ "aisix.client_identity",
+ &event.client_identity,
+ ));
+ }
  // JWT identity attribution (AISIX-Cloud#564): who the request ran as
  // when it authenticated with a JWT — the identity behind the (possibly
  // shared) api_key_id.
@@ -802,6 +812,14 @@ fn build_otlp_span(record: &SinkRecord, exporter_name: &str) -> Value {
  attributes.push(attr_string("aisix.mcp.server_name", &event.mcp_server_name));
  }
  }
+ "passthrough" => {
+ if !event.passthrough_route_name.is_empty() {
+ attributes.push(attr_string(
+ "aisix.passthrough.route_name",
+ &event.passthrough_route_name,
+ ));
+ }
+ }
  _ => {}
  }
  // Opt-in captured content (#519 B.2) — present ONLY on a record built by
@@ -841,6 +859,7 @@ fn operation_name(event: &UsageEvent) -> &'static str {
  match event.inbound_protocol.as_str() {
  "a2a" => "invoke_agent",
  "mcp" => "execute_tool",
+ "passthrough" => "passthrough",
  _ => "chat",
  }
 }
@@ -867,6 +886,9 @@ fn span_name(event: &UsageEvent) -> String {
  let target = match event.inbound_protocol.as_str() {
  "a2a" => &event.a2a_agent_name,
  "mcp" => &event.mcp_tool_name,
+ // A route name is a registered resource like an agent name, so it is
+ // operator-bounded — but it still passes the length cap below.
+ "passthrough" => &event.passthrough_route_name,
  _ => return "chat.completions".to_string(),
  };
  if target.is_empty() || target.len() > MAX_SPAN_NAME_TARGET {
@@ -1535,6 +1557,44 @@ mod tests {
  assert_eq!(string_at("aisix.a2a.task_state"), "working");
  }
 
+ #[test]
+ fn a_passthrough_relay_exports_route_and_identity_not_a_chat_span() {
+ // The passthrough handler emits usage events with
+ // `inbound_protocol = "passthrough"`; without the explicit branch a
+ // Copilot relay exported as a bare `chat.completions` span with the
+ // route and the device-injected end-user identity recorded nowhere.
+ let mut ev = sample_event();
+ ev.inbound_protocol = "passthrough".into();
+ ev.passthrough_route_name = "copilot-chat".into();
+ ev.client_identity = "alice@example.com".into();
+
+ let body = build_otlp_traces_payload(&ev, "test-exp");
+ let span = &body["resourceSpans"][0]["scopeSpans"][0]["spans"][0];
+ assert_eq!(span["name"], "passthrough copilot-chat");
+ let attrs = span["attributes"].as_array().unwrap();
+ let find = |k: &str| attrs.iter().find(|a| a["key"] == k);
+ let string_at = |k: &str| find(k).unwrap()["value"]["stringValue"].clone();
+ assert_eq!(string_at("gen_ai.operation.name"), "passthrough");
+ assert_eq!(string_at("aisix.passthrough.route_name"), "copilot-chat");
+ assert_eq!(string_at("aisix.client_identity"), "alice@example.com");
+ }
+
+ #[test]
+ fn client_identity_exports_without_a_protocol_gate() {
+ // The identity attribute must not depend on the passthrough branch:
+ // any handler that populates the field gets it exported.
+ let mut ev = sample_event();
+ ev.client_identity = "bob@example.com".into();
+ let body = build_otlp_traces_payload(&ev, "test-exp");
+ let span = &body["resourceSpans"][0]["scopeSpans"][0]["spans"][0];
+ let attrs = span["attributes"].as_array().unwrap();
+ let id = attrs
+ .iter()
+ .find(|a| a["key"] == "aisix.client_identity")
+ .unwrap();
+ assert_eq!(id["value"]["stringValue"], "bob@example.com");
+ }
+
  #[test]
  fn a_streamed_a2a_call_carries_its_event_count() {
  // A unary call has no count, and exporting a zero would read as "the

crates/aisix-proxy/src/attempt.rs

@@ -291,6 +291,7 @@ pub(crate) fn attempt_reached_upstream(err: &ProxyError) -> bool {
  ProxyError::Bridge(be) => be.reached_upstream(),
  ProxyError::ContentFiltered(_) => true,
  ProxyError::MissingAuth
+ | ProxyError::MissingRouteAuthHeader(_)
  | ProxyError::InvalidApiKey
  | ProxyError::ApiKeyExpired
  | ProxyError::ApiKeyDisabled

crates/aisix-proxy/src/error.rs

@@ -166,6 +166,13 @@ impl ErrorEnvelope {
 pub enum ProxyError {
  #[error("missing or malformed Authorization header")]
  MissingAuth,
+ /// A `header_key` passthrough route saw no gateway key in its configured
+ /// header. Named separately from [`ProxyError::MissingAuth`] because on
+ /// these routes `Authorization` deliberately carries the caller's own
+ /// upstream credential — telling the integrator to fix `Authorization`
+ /// points at exactly the wrong header.
+ #[error("missing or malformed {0} header (this route's gateway API key header)")]
+ MissingRouteAuthHeader(String),
  #[error("invalid API key")]
  InvalidApiKey,
  /// The presented key exists but its `expires_at` deadline has
@@ -336,7 +343,8 @@ pub(crate) fn guardrail_block_message(side: &str, guardrail_name: Option<&str>)
 impl ProxyError {
  pub fn status(&self) -> StatusCode {
  match self {
- ProxyError::MissingAuth
+ ProxyError::MissingRouteAuthHeader(_)
+ | ProxyError::MissingAuth
  | ProxyError::InvalidApiKey
  | ProxyError::ApiKeyExpired
  | ProxyError::ApiKeyDisabled
@@ -369,7 +377,8 @@ impl ProxyError {
 
  pub fn kind(&self) -> &'static str {
  match self {
- ProxyError::MissingAuth
+ ProxyError::MissingRouteAuthHeader(_)
+ | ProxyError::MissingAuth
  | ProxyError::InvalidApiKey
  | ProxyError::ApiKeyExpired
  | ProxyError::ApiKeyDisabled

crates/aisix-proxy/src/passthrough_route.rs

@@ -352,10 +352,7 @@ pub async fn entry(
  status,
  elapsed,
  );
- crate::usage_attr::emit_error_usage_event(
- &state,
- &snapshot,
- "passthrough_route",
+ let mut event = crate::usage_attr::build_error_usage_event(
  "passthrough",
  &request_id,
  "",
@@ -364,6 +361,16 @@ pub async fn entry(
  error.kind(),
  &client,
  );
+ // The route matched before the pipeline failed, so a rejected
+ // request still attributes to it — an operator triaging 401s
+ // per route needs the name on the event, not just in the log.
+ event.passthrough_route_name = route_name.clone();
+ crate::usage_attr::emit_prepared_usage_event(
+ &state,
+ &snapshot,
+ "passthrough_route",
+ event,
+ );
  error.into_response()
  }
  }
@@ -917,7 +924,7 @@ async fn authenticate(
  .and_then(|v| v.to_str().ok())
  .map(|v| v.strip_prefix("Bearer ").unwrap_or(v).trim().to_string())
  .filter(|v| !v.is_empty())
- .ok_or(ProxyError::MissingAuth)?;
+ .ok_or_else(|| ProxyError::MissingRouteAuthHeader(name.to_string()))?;
  crate::auth::authenticate_token(state, &token, ctx).await
  }
  PassthroughAuthMode::Anonymous => {

crates/aisix-proxy/src/usage_attr.rs

@@ -354,6 +354,30 @@ pub(crate) fn emit_error_usage_event(
  error_class: &str,
  client: &ClientContext,
 ) {
+ let event = build_error_usage_event(
+ inbound_protocol,
+ request_id,
+ requested_model,
+ api_key_id,
+ status_code,
+ error_class,
+ client,
+ );
+ emit_prepared_usage_event(state, snap, label, event);
+}
+
+/// The [`emit_error_usage_event`] event without the emission, for a caller
+/// that attributes handler-specific fields (e.g. the passthrough route name)
+/// before handing it to [`emit_prepared_usage_event`].
+pub(crate) fn build_error_usage_event(
+ inbound_protocol: &'static str,
+ request_id: &str,
+ requested_model: &str,
+ api_key_id: &str,
+ status_code: u16,
+ error_class: &str,
+ client: &ClientContext,
+) -> UsageEvent {
  let mut event = UsageEvent {
  request_id: request_id.to_string(),
  occurred_at: chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Secs, true),
@@ -367,6 +391,15 @@ pub(crate) fn emit_error_usage_event(
  ..Default::default()
  };
  apply_jwt_identity(&mut event, client.jwt.as_ref());
+ event
+}
+
+pub(crate) fn emit_prepared_usage_event(
+ state: &ProxyState,
+ snap: &AisixSnapshot,
+ label: &'static str,
+ event: UsageEvent,
+) {
  state.usage_sink.try_emit(label, event.clone());
  let exporters = live_exporters(state, snap);
  state

schemas/resources/passthrough_route.schema.json

@@ -240,6 +240,78 @@
  ]
  }
  },
+ {
+ "if": {
+ "anyOf": [
+ {
+ "not": {
+ "required": [
+ "auth_mode"
+ ]
+ },
+ "title": "auth_mode omitted (defaults to gateway_key)"
+ },
+ {
+ "properties": {
+ "auth_mode": {
+ "enum": [
+ "gateway_key",
+ "anonymous"
+ ]
+ }
+ },
+ "required": [
+ "auth_mode"
+ ],
+ "title": "auth_mode: gateway_key or anonymous"
+ }
+ ]
+ },
+ "then": {
+ "not": {
+ "required": [
+ "auth_header_name"
+ ]
+ }
+ },
+ "title": "auth_header_name only in header_key mode"
+ },
+ {
+ "if": {
+ "anyOf": [
+ {
+ "not": {
+ "required": [
+ "auth_mode"
+ ]
+ },
+ "title": "auth_mode omitted (defaults to gateway_key)"
+ },
+ {
+ "properties": {
+ "auth_mode": {
+ "enum": [
+ "gateway_key",
+ "header_key"
+ ]
+ }
+ },
+ "required": [
+ "auth_mode"
+ ],
+ "title": "auth_mode: gateway_key or header_key"
+ }
+ ]
+ },
+ "then": {
+ "not": {
+ "required": [
+ "anonymous_key_id"
+ ]
+ }
+ },
+ "title": "anonymous_key_id only in anonymous mode"
+ },
  {
  "if": {
  "anyOf": [

tests/e2e/src/cases/passthrough-route-e2e.test.ts

@@ -281,6 +281,25 @@ describe("passthrough-route e2e: explicit routes, BYO credentials, 410 tombstone
  // …and the gateway's side-channel headers did not.
  expect(hit.headers["x-aisix-api-key"]).toBeUndefined();
  expect(hit.headers["x-aisix-user"]).toBeUndefined();
+
+ // Missing gateway key: the 401 must point at the route's configured
+ // header, not `Authorization` — on this route Authorization carries the
+ // caller's own upstream credential and is exactly the wrong thing to fix.
+ const noKey = await harnessRequest(`${app!.proxyUrl}/v1/chat/completions`, {
+ method: "POST",
+ headers: {
+ host: "ai-upstream.example.com",
+ authorization: "Bearer employee-official-token",
+ "content-type": "application/json",
+ },
+ body: JSON.stringify({ model: "gpt-4o", messages: [] }),
+ });
+ expect(noKey.statusCode).toBe(401);
+ const noKeyBody = (await noKey.body.json()) as {
+ error?: { message?: string };
+ };
+ expect(noKeyBody.error?.message).toContain("x-aisix-api-key");
+ expect(noKeyBody.error?.message).not.toContain("Authorization");
  });
 
  test("anonymous route binds the configured principal behind source_cidrs", async (ctx) => {

crates/aisix-core/src/models/passthrough_route.rs

@@ -379,6 +379,30 @@ pub fn passthrough_route_coupling() -> Value {
  }
  }
  },
+ // Cross-mode leftovers are configuration errors, not ignored
+ // fields: a companion outside its mode is never consulted, so a
+ // row carrying one is rejected rather than half-honored. The CP
+ // enforces the identical rule on create and patch.
+ {
+ "title": "auth_header_name only in header_key mode",
+ "if": {
+ "anyOf": [
+ { "title": "auth_mode omitted (defaults to gateway_key)", "not": { "required": ["auth_mode"] } },
+ { "title": "auth_mode: gateway_key or anonymous", "properties": { "auth_mode": { "enum": ["gateway_key", "anonymous"] } }, "required": ["auth_mode"] }
+ ]
+ },
+ "then": { "not": { "required": ["auth_header_name"] } }
+ },
+ {
+ "title": "anonymous_key_id only in anonymous mode",
+ "if": {
+ "anyOf": [
+ { "title": "auth_mode omitted (defaults to gateway_key)", "not": { "required": ["auth_mode"] } },
+ { "title": "auth_mode: gateway_key or header_key", "properties": { "auth_mode": { "enum": ["gateway_key", "header_key"] } }, "required": ["auth_mode"] }
+ ]
+ },
+ "then": { "not": { "required": ["anonymous_key_id"] } }
+ },
  // credential_mode couplings: inject needs a real ProviderKey id; a
  // forward_client route carrying one is a configuration error, not
  // an ignored field.
@@ -516,6 +540,39 @@ mod coupling_tests {
  assert!(validate_passthrough_route(&doc).is_err());
  }
 
+ #[test]
+ fn cross_mode_leftover_companions_are_rejected() {
+ // A companion outside its mode is never consulted at runtime, so
+ // both validators refuse the row instead of half-honoring it.
+ // auth_header_name without header_key (auth_mode absent = gateway_key).
+ let mut doc = base();
+ doc["auth_header_name"] = json!("x-aisix-api-key");
+ assert!(validate_passthrough_route(&doc).is_err());
+ assert!(validate_passthrough_route_lenient(&doc).is_err());
+ // anonymous_key_id on an explicit header_key route.
+ let doc = json!({
+ "name": "r", "path_prefix": "/p",
+ "target_url": "https://u.example", "provider_key_id": "pk",
+ "auth_mode": "header_key", "auth_header_name": "x-aisix-api-key",
+ "anonymous_key_id": "ak-1"
+ });
+ assert!(validate_passthrough_route(&doc).is_err());
+ // auth_header_name on an anonymous route.
+ let doc = json!({
+ "name": "r", "path_prefix": "/p",
+ "target_url": "https://u.example", "provider_key_id": "pk",
+ "auth_mode": "anonymous", "anonymous_key_id": "ak-1",
+ "source_cidrs": ["10.0.0.0/8"],
+ "auth_header_name": "x-aisix-api-key"
+ });
+ assert!(validate_passthrough_route(&doc).is_err());
+ // source_cidrs is deliberately NOT mode-coupled: an extra IP
+ // allowlist is honored on every mode.
+ let mut doc = base();
+ doc["source_cidrs"] = json!(["10.0.0.0/8"]);
+ assert!(validate_passthrough_route(&doc).is_ok());
+ }
+
  #[test]
  fn credential_bearing_header_slots_are_rejected() {
  for field in ["auth_header_name", "identity_header"] {

crates/aisix-obs/src/otlp_http_sink.rs

@@ -743,6 +743,16 @@ fn build_otlp_span(record: &SinkRecord, exporter_name: &str) -> Value {
  &event.client_user_agent,
  ));
  }
+ // End-user identity a passthrough route's `identity_header` extracted —
+ // the per-employee attribution of the forward-proxy scenario. Not gated
+ // on the protocol so a future handler that learns to populate it exports
+ // it without touching this sink.
+ if !event.client_identity.is_empty() {
+ attributes.push(attr_string_capped(
+ "aisix.client_identity",
+ &event.client_identity,
+ ));
+ }
  // JWT identity attribution (AISIX-Cloud#564): who the request ran as
  // when it authenticated with a JWT — the identity behind the (possibly
  // shared) api_key_id.
@@ -802,6 +812,14 @@ fn build_otlp_span(record: &SinkRecord, exporter_name: &str) -> Value {
  attributes.push(attr_string("aisix.mcp.server_name", &event.mcp_server_name));
  }
  }
+ "passthrough" => {
+ if !event.passthrough_route_name.is_empty() {
+ attributes.push(attr_string(
+ "aisix.passthrough.route_name",
+ &event.passthrough_route_name,
+ ));
+ }
+ }
  _ => {}
  }
  // Opt-in captured content (#519 B.2) — present ONLY on a record built by
@@ -841,6 +859,7 @@ fn operation_name(event: &UsageEvent) -> &'static str {
  match event.inbound_protocol.as_str() {
  "a2a" => "invoke_agent",
  "mcp" => "execute_tool",
+ "passthrough" => "passthrough",
  _ => "chat",
  }
 }
@@ -867,6 +886,9 @@ fn span_name(event: &UsageEvent) -> String {
  let target = match event.inbound_protocol.as_str() {
  "a2a" => &event.a2a_agent_name,
  "mcp" => &event.mcp_tool_name,
+ // A route name is a registered resource like an agent name, so it is
+ // operator-bounded — but it still passes the length cap below.
+ "passthrough" => &event.passthrough_route_name,
  _ => return "chat.completions".to_string(),
  };
  if target.is_empty() || target.len() > MAX_SPAN_NAME_TARGET {
@@ -1535,6 +1557,44 @@ mod tests {
  assert_eq!(string_at("aisix.a2a.task_state"), "working");
  }
 
+ #[test]
+ fn a_passthrough_relay_exports_route_and_identity_not_a_chat_span() {
+ // The passthrough handler emits usage events with
+ // `inbound_protocol = "passthrough"`; without the explicit branch a
+ // Copilot relay exported as a bare `chat.completions` span with the
+ // route and the device-injected end-user identity recorded nowhere.
+ let mut ev = sample_event();
+ ev.inbound_protocol = "passthrough".into();
+ ev.passthrough_route_name = "copilot-chat".into();
+ ev.client_identity = "alice@example.com".into();
+
+ let body = build_otlp_traces_payload(&ev, "test-exp");
+ let span = &body["resourceSpans"][0]["scopeSpans"][0]["spans"][0];
+ assert_eq!(span["name"], "passthrough copilot-chat");
+ let attrs = span["attributes"].as_array().unwrap();
+ let find = |k: &str| attrs.iter().find(|a| a["key"] == k);
+ let string_at = |k: &str| find(k).unwrap()["value"]["stringValue"].clone();
+ assert_eq!(string_at("gen_ai.operation.name"), "passthrough");
+ assert_eq!(string_at("aisix.passthrough.route_name"), "copilot-chat");
+ assert_eq!(string_at("aisix.client_identity"), "alice@example.com");
+ }
+
+ #[test]
+ fn client_identity_exports_without_a_protocol_gate() {
+ // The identity attribute must not depend on the passthrough branch:
+ // any handler that populates the field gets it exported.
+ let mut ev = sample_event();
+ ev.client_identity = "bob@example.com".into();
+ let body = build_otlp_traces_payload(&ev, "test-exp");
+ let span = &body["resourceSpans"][0]["scopeSpans"][0]["spans"][0];
+ let attrs = span["attributes"].as_array().unwrap();
+ let id = attrs
+ .iter()
+ .find(|a| a["key"] == "aisix.client_identity")
+ .unwrap();
+ assert_eq!(id["value"]["stringValue"], "bob@example.com");
+ }
+
  #[test]
  fn a_streamed_a2a_call_carries_its_event_count() {
  // A unary call has no count, and exporting a zero would read as "the

crates/aisix-proxy/src/attempt.rs

@@ -291,6 +291,7 @@ pub(crate) fn attempt_reached_upstream(err: &ProxyError) -> bool {
  ProxyError::Bridge(be) => be.reached_upstream(),
  ProxyError::ContentFiltered(_) => true,
  ProxyError::MissingAuth
+ | ProxyError::MissingRouteAuthHeader(_)
  | ProxyError::InvalidApiKey
  | ProxyError::ApiKeyExpired
  | ProxyError::ApiKeyDisabled

crates/aisix-proxy/src/error.rs

@@ -166,6 +166,13 @@ impl ErrorEnvelope {
 pub enum ProxyError {
  #[error("missing or malformed Authorization header")]
  MissingAuth,
+ /// A `header_key` passthrough route saw no gateway key in its configured
+ /// header. Named separately from [`ProxyError::MissingAuth`] because on
+ /// these routes `Authorization` deliberately carries the caller's own
+ /// upstream credential — telling the integrator to fix `Authorization`
+ /// points at exactly the wrong header.
+ #[error("missing or malformed {0} header (this route's gateway API key header)")]
+ MissingRouteAuthHeader(String),
  #[error("invalid API key")]
  InvalidApiKey,
  /// The presented key exists but its `expires_at` deadline has
@@ -336,7 +343,8 @@ pub(crate) fn guardrail_block_message(side: &str, guardrail_name: Option<&str>)
 impl ProxyError {
  pub fn status(&self) -> StatusCode {
  match self {
- ProxyError::MissingAuth
+ ProxyError::MissingRouteAuthHeader(_)
+ | ProxyError::MissingAuth
  | ProxyError::InvalidApiKey
  | ProxyError::ApiKeyExpired
  | ProxyError::ApiKeyDisabled
@@ -369,7 +377,8 @@ impl ProxyError {
 
  pub fn kind(&self) -> &'static str {
  match self {
- ProxyError::MissingAuth
+ ProxyError::MissingRouteAuthHeader(_)
+ | ProxyError::MissingAuth
  | ProxyError::InvalidApiKey
  | ProxyError::ApiKeyExpired
  | ProxyError::ApiKeyDisabled

crates/aisix-proxy/src/passthrough_route.rs

@@ -352,10 +352,7 @@ pub async fn entry(
  status,
  elapsed,
  );
- crate::usage_attr::emit_error_usage_event(
- &state,
- &snapshot,
- "passthrough_route",
+ let mut event = crate::usage_attr::build_error_usage_event(
  "passthrough",
  &request_id,
  "",
@@ -364,6 +361,16 @@ pub async fn entry(
  error.kind(),
  &client,
  );
+ // The route matched before the pipeline failed, so a rejected
+ // request still attributes to it — an operator triaging 401s
+ // per route needs the name on the event, not just in the log.
+ event.passthrough_route_name = route_name.clone();
+ crate::usage_attr::emit_prepared_usage_event(
+ &state,
+ &snapshot,
+ "passthrough_route",
+ event,
+ );
  error.into_response()
  }
  }
@@ -917,7 +924,7 @@ async fn authenticate(
  .and_then(|v| v.to_str().ok())
  .map(|v| v.strip_prefix("Bearer ").unwrap_or(v).trim().to_string())
  .filter(|v| !v.is_empty())
- .ok_or(ProxyError::MissingAuth)?;
+ .ok_or_else(|| ProxyError::MissingRouteAuthHeader(name.to_string()))?;
  crate::auth::authenticate_token(state, &token, ctx).await
  }
  PassthroughAuthMode::Anonymous => {

crates/aisix-proxy/src/usage_attr.rs

@@ -354,6 +354,30 @@ pub(crate) fn emit_error_usage_event(
  error_class: &str,
  client: &ClientContext,
 ) {
+ let event = build_error_usage_event(
+ inbound_protocol,
+ request_id,
+ requested_model,
+ api_key_id,
+ status_code,
+ error_class,
+ client,
+ );
+ emit_prepared_usage_event(state, snap, label, event);
+}
+
+/// The [`emit_error_usage_event`] event without the emission, for a caller
+/// that attributes handler-specific fields (e.g. the passthrough route name)
+/// before handing it to [`emit_prepared_usage_event`].
+pub(crate) fn build_error_usage_event(
+ inbound_protocol: &'static str,
+ request_id: &str,
+ requested_model: &str,
+ api_key_id: &str,
+ status_code: u16,
+ error_class: &str,
+ client: &ClientContext,
+) -> UsageEvent {
  let mut event = UsageEvent {
  request_id: request_id.to_string(),
  occurred_at: chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Secs, true),
@@ -367,6 +391,15 @@ pub(crate) fn emit_error_usage_event(
  ..Default::default()
  };
  apply_jwt_identity(&mut event, client.jwt.as_ref());
+ event
+}
+
+pub(crate) fn emit_prepared_usage_event(
+ state: &ProxyState,
+ snap: &AisixSnapshot,
+ label: &'static str,
+ event: UsageEvent,
+) {
  state.usage_sink.try_emit(label, event.clone());
  let exporters = live_exporters(state, snap);
  state

schemas/resources/passthrough_route.schema.json

@@ -240,6 +240,78 @@
  ]
  }
  },
+ {
+ "if": {
+ "anyOf": [
+ {
+ "not": {
+ "required": [
+ "auth_mode"
+ ]
+ },
+ "title": "auth_mode omitted (defaults to gateway_key)"
+ },
+ {
+ "properties": {
+ "auth_mode": {
+ "enum": [
+ "gateway_key",
+ "anonymous"
+ ]
+ }
+ },
+ "required": [
+ "auth_mode"
+ ],
+ "title": "auth_mode: gateway_key or anonymous"
+ }
+ ]
+ },
+ "then": {
+ "not": {
+ "required": [
+ "auth_header_name"
+ ]
+ }
+ },
+ "title": "auth_header_name only in header_key mode"
+ },
+ {
+ "if": {
+ "anyOf": [
+ {
+ "not": {
+ "required": [
+ "auth_mode"
+ ]
+ },
+ "title": "auth_mode omitted (defaults to gateway_key)"
+ },
+ {
+ "properties": {
+ "auth_mode": {
+ "enum": [
+ "gateway_key",
+ "header_key"
+ ]
+ }
+ },
+ "required": [
+ "auth_mode"
+ ],
+ "title": "auth_mode: gateway_key or header_key"
+ }
+ ]
+ },
+ "then": {
+ "not": {
+ "required": [
+ "anonymous_key_id"
+ ]
+ }
+ },
+ "title": "anonymous_key_id only in anonymous mode"
+ },
  {
  "if": {
  "anyOf": [

tests/e2e/src/cases/passthrough-route-e2e.test.ts

@@ -281,6 +281,25 @@ describe("passthrough-route e2e: explicit routes, BYO credentials, 410 tombstone
  // …and the gateway's side-channel headers did not.
  expect(hit.headers["x-aisix-api-key"]).toBeUndefined();
  expect(hit.headers["x-aisix-user"]).toBeUndefined();
+
+ // Missing gateway key: the 401 must point at the route's configured
+ // header, not `Authorization` — on this route Authorization carries the
+ // caller's own upstream credential and is exactly the wrong thing to fix.
+ const noKey = await harnessRequest(`${app!.proxyUrl}/v1/chat/completions`, {
+ method: "POST",
+ headers: {
+ host: "ai-upstream.example.com",
+ authorization: "Bearer employee-official-token",
+ "content-type": "application/json",
+ },
+ body: JSON.stringify({ model: "gpt-4o", messages: [] }),
+ });
+ expect(noKey.statusCode).toBe(401);
+ const noKeyBody = (await noKey.body.json()) as {
+ error?: { message?: string };
+ };
+ expect(noKeyBody.error?.message).toContain("x-aisix-api-key");
+ expect(noKeyBody.error?.message).not.toContain("Authorization");
  });
 
  test("anonymous route binds the configured principal behind source_cidrs", async (ctx) => {

crates/aisix-core/src/models/passthrough_route.rs

@@ -379,6 +379,30 @@ pub fn passthrough_route_coupling() -> Value {
  }
  }
  },
+ // Cross-mode leftovers are configuration errors, not ignored
+ // fields: a companion outside its mode is never consulted, so a
+ // row carrying one is rejected rather than half-honored. The CP
+ // enforces the identical rule on create and patch.
+ {
+ "title": "auth_header_name only in header_key mode",
+ "if": {
+ "anyOf": [
+ { "title": "auth_mode omitted (defaults to gateway_key)", "not": { "required": ["auth_mode"] } },
+ { "title": "auth_mode: gateway_key or anonymous", "properties": { "auth_mode": { "enum": ["gateway_key", "anonymous"] } }, "required": ["auth_mode"] }
+ ]
+ },
+ "then": { "not": { "required": ["auth_header_name"] } }
+ },
+ {
+ "title": "anonymous_key_id only in anonymous mode",
+ "if": {
+ "anyOf": [
+ { "title": "auth_mode omitted (defaults to gateway_key)", "not": { "required": ["auth_mode"] } },
+ { "title": "auth_mode: gateway_key or header_key", "properties": { "auth_mode": { "enum": ["gateway_key", "header_key"] } }, "required": ["auth_mode"] }
+ ]
+ },
+ "then": { "not": { "required": ["anonymous_key_id"] } }
+ },
  // credential_mode couplings: inject needs a real ProviderKey id; a
  // forward_client route carrying one is a configuration error, not
  // an ignored field.
@@ -516,6 +540,39 @@ mod coupling_tests {
  assert!(validate_passthrough_route(&doc).is_err());
  }
 
+ #[test]
+ fn cross_mode_leftover_companions_are_rejected() {
+ // A companion outside its mode is never consulted at runtime, so
+ // both validators refuse the row instead of half-honoring it.
+ // auth_header_name without header_key (auth_mode absent = gateway_key).
+ let mut doc = base();
+ doc["auth_header_name"] = json!("x-aisix-api-key");
+ assert!(validate_passthrough_route(&doc).is_err());
+ assert!(validate_passthrough_route_lenient(&doc).is_err());
+ // anonymous_key_id on an explicit header_key route.
+ let doc = json!({
+ "name": "r", "path_prefix": "/p",
+ "target_url": "https://u.example", "provider_key_id": "pk",
+ "auth_mode": "header_key", "auth_header_name": "x-aisix-api-key",
+ "anonymous_key_id": "ak-1"
+ });
+ assert!(validate_passthrough_route(&doc).is_err());
+ // auth_header_name on an anonymous route.
+ let doc = json!({
+ "name": "r", "path_prefix": "/p",
+ "target_url": "https://u.example", "provider_key_id": "pk",
+ "auth_mode": "anonymous", "anonymous_key_id": "ak-1",
+ "source_cidrs": ["10.0.0.0/8"],
+ "auth_header_name": "x-aisix-api-key"
+ });
+ assert!(validate_passthrough_route(&doc).is_err());
+ // source_cidrs is deliberately NOT mode-coupled: an extra IP
+ // allowlist is honored on every mode.
+ let mut doc = base();
+ doc["source_cidrs"] = json!(["10.0.0.0/8"]);
+ assert!(validate_passthrough_route(&doc).is_ok());
+ }
+
  #[test]
  fn credential_bearing_header_slots_are_rejected() {
  for field in ["auth_header_name", "identity_header"] {

crates/aisix-obs/src/otlp_http_sink.rs

@@ -743,6 +743,16 @@ fn build_otlp_span(record: &SinkRecord, exporter_name: &str) -> Value {
  &event.client_user_agent,
  ));
  }
+ // End-user identity a passthrough route's `identity_header` extracted —
+ // the per-employee attribution of the forward-proxy scenario. Not gated
+ // on the protocol so a future handler that learns to populate it exports
+ // it without touching this sink.
+ if !event.client_identity.is_empty() {
+ attributes.push(attr_string_capped(
+ "aisix.client_identity",
+ &event.client_identity,
+ ));
+ }
  // JWT identity attribution (AISIX-Cloud#564): who the request ran as
  // when it authenticated with a JWT — the identity behind the (possibly
  // shared) api_key_id.
@@ -802,6 +812,14 @@ fn build_otlp_span(record: &SinkRecord, exporter_name: &str) -> Value {
  attributes.push(attr_string("aisix.mcp.server_name", &event.mcp_server_name));
  }
  }
+ "passthrough" => {
+ if !event.passthrough_route_name.is_empty() {
+ attributes.push(attr_string(
+ "aisix.passthrough.route_name",
+ &event.passthrough_route_name,
+ ));
+ }
+ }
  _ => {}
  }
  // Opt-in captured content (#519 B.2) — present ONLY on a record built by
@@ -841,6 +859,7 @@ fn operation_name(event: &UsageEvent) -> &'static str {
  match event.inbound_protocol.as_str() {
  "a2a" => "invoke_agent",
  "mcp" => "execute_tool",
+ "passthrough" => "passthrough",
  _ => "chat",
  }
 }
@@ -867,6 +886,9 @@ fn span_name(event: &UsageEvent) -> String {
  let target = match event.inbound_protocol.as_str() {
  "a2a" => &event.a2a_agent_name,
  "mcp" => &event.mcp_tool_name,
+ // A route name is a registered resource like an agent name, so it is
+ // operator-bounded — but it still passes the length cap below.
+ "passthrough" => &event.passthrough_route_name,
  _ => return "chat.completions".to_string(),
  };
  if target.is_empty() || target.len() > MAX_SPAN_NAME_TARGET {
@@ -1535,6 +1557,44 @@ mod tests {
  assert_eq!(string_at("aisix.a2a.task_state"), "working");
  }
 
+ #[test]
+ fn a_passthrough_relay_exports_route_and_identity_not_a_chat_span() {
+ // The passthrough handler emits usage events with
+ // `inbound_protocol = "passthrough"`; without the explicit branch a
+ // Copilot relay exported as a bare `chat.completions` span with the
+ // route and the device-injected end-user identity recorded nowhere.
+ let mut ev = sample_event();
+ ev.inbound_protocol = "passthrough".into();
+ ev.passthrough_route_name = "copilot-chat".into();
+ ev.client_identity = "alice@example.com".into();
+
+ let body = build_otlp_traces_payload(&ev, "test-exp");
+ let span = &body["resourceSpans"][0]["scopeSpans"][0]["spans"][0];
+ assert_eq!(span["name"], "passthrough copilot-chat");
+ let attrs = span["attributes"].as_array().unwrap();
+ let find = |k: &str| attrs.iter().find(|a| a["key"] == k);
+ let string_at = |k: &str| find(k).unwrap()["value"]["stringValue"].clone();
+ assert_eq!(string_at("gen_ai.operation.name"), "passthrough");
+ assert_eq!(string_at("aisix.passthrough.route_name"), "copilot-chat");
+ assert_eq!(string_at("aisix.client_identity"), "alice@example.com");
+ }
+
+ #[test]
+ fn client_identity_exports_without_a_protocol_gate() {
+ // The identity attribute must not depend on the passthrough branch:
+ // any handler that populates the field gets it exported.
+ let mut ev = sample_event();
+ ev.client_identity = "bob@example.com".into();
+ let body = build_otlp_traces_payload(&ev, "test-exp");
+ let span = &body["resourceSpans"][0]["scopeSpans"][0]["spans"][0];
+ let attrs = span["attributes"].as_array().unwrap();
+ let id = attrs
+ .iter()
+ .find(|a| a["key"] == "aisix.client_identity")
+ .unwrap();
+ assert_eq!(id["value"]["stringValue"], "bob@example.com");
+ }
+
  #[test]
  fn a_streamed_a2a_call_carries_its_event_count() {
  // A unary call has no count, and exporting a zero would read as "the

crates/aisix-proxy/src/attempt.rs

@@ -291,6 +291,7 @@ pub(crate) fn attempt_reached_upstream(err: &ProxyError) -> bool {
  ProxyError::Bridge(be) => be.reached_upstream(),
  ProxyError::ContentFiltered(_) => true,
  ProxyError::MissingAuth
+ | ProxyError::MissingRouteAuthHeader(_)
  | ProxyError::InvalidApiKey
  | ProxyError::ApiKeyExpired
  | ProxyError::ApiKeyDisabled

crates/aisix-proxy/src/error.rs

@@ -166,6 +166,13 @@ impl ErrorEnvelope {
 pub enum ProxyError {
  #[error("missing or malformed Authorization header")]
  MissingAuth,
+ /// A `header_key` passthrough route saw no gateway key in its configured
+ /// header. Named separately from [`ProxyError::MissingAuth`] because on
+ /// these routes `Authorization` deliberately carries the caller's own
+ /// upstream credential — telling the integrator to fix `Authorization`
+ /// points at exactly the wrong header.
+ #[error("missing or malformed {0} header (this route's gateway API key header)")]
+ MissingRouteAuthHeader(String),
  #[error("invalid API key")]
  InvalidApiKey,
  /// The presented key exists but its `expires_at` deadline has
@@ -336,7 +343,8 @@ pub(crate) fn guardrail_block_message(side: &str, guardrail_name: Option<&str>)
 impl ProxyError {
  pub fn status(&self) -> StatusCode {
  match self {
- ProxyError::MissingAuth
+ ProxyError::MissingRouteAuthHeader(_)
+ | ProxyError::MissingAuth
  | ProxyError::InvalidApiKey
  | ProxyError::ApiKeyExpired
  | ProxyError::ApiKeyDisabled
@@ -369,7 +377,8 @@ impl ProxyError {
 
  pub fn kind(&self) -> &'static str {
  match self {
- ProxyError::MissingAuth
+ ProxyError::MissingRouteAuthHeader(_)
+ | ProxyError::MissingAuth
  | ProxyError::InvalidApiKey
  | ProxyError::ApiKeyExpired
  | ProxyError::ApiKeyDisabled

crates/aisix-proxy/src/passthrough_route.rs

@@ -352,10 +352,7 @@ pub async fn entry(
  status,
  elapsed,
  );
- crate::usage_attr::emit_error_usage_event(
- &state,
- &snapshot,
- "passthrough_route",
+ let mut event = crate::usage_attr::build_error_usage_event(
  "passthrough",
  &request_id,
  "",
@@ -364,6 +361,16 @@ pub async fn entry(
  error.kind(),
  &client,
  );
+ // The route matched before the pipeline failed, so a rejected
+ // request still attributes to it — an operator triaging 401s
+ // per route needs the name on the event, not just in the log.
+ event.passthrough_route_name = route_name.clone();
+ crate::usage_attr::emit_prepared_usage_event(
+ &state,
+ &snapshot,
+ "passthrough_route",
+ event,
+ );
  error.into_response()
  }
  }
@@ -917,7 +924,7 @@ async fn authenticate(
  .and_then(|v| v.to_str().ok())
  .map(|v| v.strip_prefix("Bearer ").unwrap_or(v).trim().to_string())
  .filter(|v| !v.is_empty())
- .ok_or(ProxyError::MissingAuth)?;
+ .ok_or_else(|| ProxyError::MissingRouteAuthHeader(name.to_string()))?;
  crate::auth::authenticate_token(state, &token, ctx).await
  }
  PassthroughAuthMode::Anonymous => {

crates/aisix-proxy/src/usage_attr.rs

@@ -354,6 +354,30 @@ pub(crate) fn emit_error_usage_event(
  error_class: &str,
  client: &ClientContext,
 ) {
+ let event = build_error_usage_event(
+ inbound_protocol,
+ request_id,
+ requested_model,
+ api_key_id,
+ status_code,
+ error_class,
+ client,
+ );
+ emit_prepared_usage_event(state, snap, label, event);
+}
+
+/// The [`emit_error_usage_event`] event without the emission, for a caller
+/// that attributes handler-specific fields (e.g. the passthrough route name)
+/// before handing it to [`emit_prepared_usage_event`].
+pub(crate) fn build_error_usage_event(
+ inbound_protocol: &'static str,
+ request_id: &str,
+ requested_model: &str,
+ api_key_id: &str,
+ status_code: u16,
+ error_class: &str,
+ client: &ClientContext,
+) -> UsageEvent {
  let mut event = UsageEvent {
  request_id: request_id.to_string(),
  occurred_at: chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Secs, true),
@@ -367,6 +391,15 @@ pub(crate) fn emit_error_usage_event(
  ..Default::default()
  };
  apply_jwt_identity(&mut event, client.jwt.as_ref());
+ event
+}
+
+pub(crate) fn emit_prepared_usage_event(
+ state: &ProxyState,
+ snap: &AisixSnapshot,
+ label: &'static str,
+ event: UsageEvent,
+) {
  state.usage_sink.try_emit(label, event.clone());
  let exporters = live_exporters(state, snap);
  state

schemas/resources/passthrough_route.schema.json

@@ -240,6 +240,78 @@
  ]
  }
  },
+ {
+ "if": {
+ "anyOf": [
+ {
+ "not": {
+ "required": [
+ "auth_mode"
+ ]
+ },
+ "title": "auth_mode omitted (defaults to gateway_key)"
+ },
+ {
+ "properties": {
+ "auth_mode": {
+ "enum": [
+ "gateway_key",
+ "anonymous"
+ ]
+ }
+ },
+ "required": [
+ "auth_mode"
+ ],
+ "title": "auth_mode: gateway_key or anonymous"
+ }
+ ]
+ },
+ "then": {
+ "not": {
+ "required": [
+ "auth_header_name"
+ ]
+ }
+ },
+ "title": "auth_header_name only in header_key mode"
+ },
+ {
+ "if": {
+ "anyOf": [
+ {
+ "not": {
+ "required": [
+ "auth_mode"
+ ]
+ },
+ "title": "auth_mode omitted (defaults to gateway_key)"
+ },
+ {
+ "properties": {
+ "auth_mode": {
+ "enum": [
+ "gateway_key",
+ "header_key"
+ ]
+ }
+ },
+ "required": [
+ "auth_mode"
+ ],
+ "title": "auth_mode: gateway_key or header_key"
+ }
+ ]
+ },
+ "then": {
+ "not": {
+ "required": [
+ "anonymous_key_id"
+ ]
+ }
+ },
+ "title": "anonymous_key_id only in anonymous mode"
+ },
  {
  "if": {
  "anyOf": [

tests/e2e/src/cases/passthrough-route-e2e.test.ts

@@ -281,6 +281,25 @@ describe("passthrough-route e2e: explicit routes, BYO credentials, 410 tombstone
  // …and the gateway's side-channel headers did not.
  expect(hit.headers["x-aisix-api-key"]).toBeUndefined();
  expect(hit.headers["x-aisix-user"]).toBeUndefined();
+
+ // Missing gateway key: the 401 must point at the route's configured
+ // header, not `Authorization` — on this route Authorization carries the
+ // caller's own upstream credential and is exactly the wrong thing to fix.
+ const noKey = await harnessRequest(`${app!.proxyUrl}/v1/chat/completions`, {
+ method: "POST",
+ headers: {
+ host: "ai-upstream.example.com",
+ authorization: "Bearer employee-official-token",
+ "content-type": "application/json",
+ },
+ body: JSON.stringify({ model: "gpt-4o", messages: [] }),
+ });
+ expect(noKey.statusCode).toBe(401);
+ const noKeyBody = (await noKey.body.json()) as {
+ error?: { message?: string };
+ };
+ expect(noKeyBody.error?.message).toContain("x-aisix-api-key");
+ expect(noKeyBody.error?.message).not.toContain("Authorization");
  });
 
  test("anonymous route binds the configured principal behind source_cidrs", async (ctx) => {

crates/aisix-core/src/models/passthrough_route.rs

@@ -379,6 +379,30 @@ pub fn passthrough_route_coupling() -> Value {
  }
  }
  },
+ // Cross-mode leftovers are configuration errors, not ignored
+ // fields: a companion outside its mode is never consulted, so a
+ // row carrying one is rejected rather than half-honored. The CP
+ // enforces the identical rule on create and patch.
+ {
+ "title": "auth_header_name only in header_key mode",
+ "if": {
+ "anyOf": [
+ { "title": "auth_mode omitted (defaults to gateway_key)", "not": { "required": ["auth_mode"] } },
+ { "title": "auth_mode: gateway_key or anonymous", "properties": { "auth_mode": { "enum": ["gateway_key", "anonymous"] } }, "required": ["auth_mode"] }
+ ]
+ },
+ "then": { "not": { "required": ["auth_header_name"] } }
+ },
+ {
+ "title": "anonymous_key_id only in anonymous mode",
+ "if": {
+ "anyOf": [
+ { "title": "auth_mode omitted (defaults to gateway_key)", "not": { "required": ["auth_mode"] } },
+ { "title": "auth_mode: gateway_key or header_key", "properties": { "auth_mode": { "enum": ["gateway_key", "header_key"] } }, "required": ["auth_mode"] }
+ ]
+ },
+ "then": { "not": { "required": ["anonymous_key_id"] } }
+ },
  // credential_mode couplings: inject needs a real ProviderKey id; a
  // forward_client route carrying one is a configuration error, not
  // an ignored field.
@@ -516,6 +540,39 @@ mod coupling_tests {
  assert!(validate_passthrough_route(&doc).is_err());
  }
 
+ #[test]
+ fn cross_mode_leftover_companions_are_rejected() {
+ // A companion outside its mode is never consulted at runtime, so
+ // both validators refuse the row instead of half-honoring it.
+ // auth_header_name without header_key (auth_mode absent = gateway_key).
+ let mut doc = base();
+ doc["auth_header_name"] = json!("x-aisix-api-key");
+ assert!(validate_passthrough_route(&doc).is_err());
+ assert!(validate_passthrough_route_lenient(&doc).is_err());
+ // anonymous_key_id on an explicit header_key route.
+ let doc = json!({
+ "name": "r", "path_prefix": "/p",
+ "target_url": "https://u.example", "provider_key_id": "pk",
+ "auth_mode": "header_key", "auth_header_name": "x-aisix-api-key",
+ "anonymous_key_id": "ak-1"
+ });
+ assert!(validate_passthrough_route(&doc).is_err());
+ // auth_header_name on an anonymous route.
+ let doc = json!({
+ "name": "r", "path_prefix": "/p",
+ "target_url": "https://u.example", "provider_key_id": "pk",
+ "auth_mode": "anonymous", "anonymous_key_id": "ak-1",
+ "source_cidrs": ["10.0.0.0/8"],
+ "auth_header_name": "x-aisix-api-key"
+ });
+ assert!(validate_passthrough_route(&doc).is_err());
+ // source_cidrs is deliberately NOT mode-coupled: an extra IP
+ // allowlist is honored on every mode.
+ let mut doc = base();
+ doc["source_cidrs"] = json!(["10.0.0.0/8"]);
+ assert!(validate_passthrough_route(&doc).is_ok());
+ }
+
  #[test]
  fn credential_bearing_header_slots_are_rejected() {
  for field in ["auth_header_name", "identity_header"] {

crates/aisix-obs/src/otlp_http_sink.rs

@@ -743,6 +743,16 @@ fn build_otlp_span(record: &SinkRecord, exporter_name: &str) -> Value {
  &event.client_user_agent,
  ));
  }
+ // End-user identity a passthrough route's `identity_header` extracted —
+ // the per-employee attribution of the forward-proxy scenario. Not gated
+ // on the protocol so a future handler that learns to populate it exports
+ // it without touching this sink.
+ if !event.client_identity.is_empty() {
+ attributes.push(attr_string_capped(
+ "aisix.client_identity",
+ &event.client_identity,
+ ));
+ }
  // JWT identity attribution (AISIX-Cloud#564): who the request ran as
  // when it authenticated with a JWT — the identity behind the (possibly
  // shared) api_key_id.
@@ -802,6 +812,14 @@ fn build_otlp_span(record: &SinkRecord, exporter_name: &str) -> Value {
  attributes.push(attr_string("aisix.mcp.server_name", &event.mcp_server_name));
  }
  }
+ "passthrough" => {
+ if !event.passthrough_route_name.is_empty() {
+ attributes.push(attr_string(
+ "aisix.passthrough.route_name",
+ &event.passthrough_route_name,
+ ));
+ }
+ }
  _ => {}
  }
  // Opt-in captured content (#519 B.2) — present ONLY on a record built by
@@ -841,6 +859,7 @@ fn operation_name(event: &UsageEvent) -> &'static str {
  match event.inbound_protocol.as_str() {
  "a2a" => "invoke_agent",
  "mcp" => "execute_tool",
+ "passthrough" => "passthrough",
  _ => "chat",
  }
 }
@@ -867,6 +886,9 @@ fn span_name(event: &UsageEvent) -> String {
  let target = match event.inbound_protocol.as_str() {
  "a2a" => &event.a2a_agent_name,
  "mcp" => &event.mcp_tool_name,
+ // A route name is a registered resource like an agent name, so it is
+ // operator-bounded — but it still passes the length cap below.
+ "passthrough" => &event.passthrough_route_name,
  _ => return "chat.completions".to_string(),
  };
  if target.is_empty() || target.len() > MAX_SPAN_NAME_TARGET {
@@ -1535,6 +1557,44 @@ mod tests {
  assert_eq!(string_at("aisix.a2a.task_state"), "working");
  }
 
+ #[test]
+ fn a_passthrough_relay_exports_route_and_identity_not_a_chat_span() {
+ // The passthrough handler emits usage events with
+ // `inbound_protocol = "passthrough"`; without the explicit branch a
+ // Copilot relay exported as a bare `chat.completions` span with the
+ // route and the device-injected end-user identity recorded nowhere.
+ let mut ev = sample_event();
+ ev.inbound_protocol = "passthrough".into();
+ ev.passthrough_route_name = "copilot-chat".into();
+ ev.client_identity = "alice@example.com".into();
+
+ let body = build_otlp_traces_payload(&ev, "test-exp");
+ let span = &body["resourceSpans"][0]["scopeSpans"][0]["spans"][0];
+ assert_eq!(span["name"], "passthrough copilot-chat");
+ let attrs = span["attributes"].as_array().unwrap();
+ let find = |k: &str| attrs.iter().find(|a| a["key"] == k);
+ let string_at = |k: &str| find(k).unwrap()["value"]["stringValue"].clone();
+ assert_eq!(string_at("gen_ai.operation.name"), "passthrough");
+ assert_eq!(string_at("aisix.passthrough.route_name"), "copilot-chat");
+ assert_eq!(string_at("aisix.client_identity"), "alice@example.com");
+ }
+
+ #[test]
+ fn client_identity_exports_without_a_protocol_gate() {
+ // The identity attribute must not depend on the passthrough branch:
+ // any handler that populates the field gets it exported.
+ let mut ev = sample_event();
+ ev.client_identity = "bob@example.com".into();
+ let body = build_otlp_traces_payload(&ev, "test-exp");
+ let span = &body["resourceSpans"][0]["scopeSpans"][0]["spans"][0];
+ let attrs = span["attributes"].as_array().unwrap();
+ let id = attrs
+ .iter()
+ .find(|a| a["key"] == "aisix.client_identity")
+ .unwrap();
+ assert_eq!(id["value"]["stringValue"], "bob@example.com");
+ }
+
  #[test]
  fn a_streamed_a2a_call_carries_its_event_count() {
  // A unary call has no count, and exporting a zero would read as "the

crates/aisix-proxy/src/attempt.rs

@@ -291,6 +291,7 @@ pub(crate) fn attempt_reached_upstream(err: &ProxyError) -> bool {
  ProxyError::Bridge(be) => be.reached_upstream(),
  ProxyError::ContentFiltered(_) => true,
  ProxyError::MissingAuth
+ | ProxyError::MissingRouteAuthHeader(_)
  | ProxyError::InvalidApiKey
  | ProxyError::ApiKeyExpired
  | ProxyError::ApiKeyDisabled

crates/aisix-proxy/src/error.rs

@@ -166,6 +166,13 @@ impl ErrorEnvelope {
 pub enum ProxyError {
  #[error("missing or malformed Authorization header")]
  MissingAuth,
+ /// A `header_key` passthrough route saw no gateway key in its configured
+ /// header. Named separately from [`ProxyError::MissingAuth`] because on
+ /// these routes `Authorization` deliberately carries the caller's own
+ /// upstream credential — telling the integrator to fix `Authorization`
+ /// points at exactly the wrong header.
+ #[error("missing or malformed {0} header (this route's gateway API key header)")]
+ MissingRouteAuthHeader(String),
  #[error("invalid API key")]
  InvalidApiKey,
  /// The presented key exists but its `expires_at` deadline has
@@ -336,7 +343,8 @@ pub(crate) fn guardrail_block_message(side: &str, guardrail_name: Option<&str>)
 impl ProxyError {
  pub fn status(&self) -> StatusCode {
  match self {
- ProxyError::MissingAuth
+ ProxyError::MissingRouteAuthHeader(_)
+ | ProxyError::MissingAuth
  | ProxyError::InvalidApiKey
  | ProxyError::ApiKeyExpired
  | ProxyError::ApiKeyDisabled
@@ -369,7 +377,8 @@ impl ProxyError {
 
  pub fn kind(&self) -> &'static str {
  match self {
- ProxyError::MissingAuth
+ ProxyError::MissingRouteAuthHeader(_)
+ | ProxyError::MissingAuth
  | ProxyError::InvalidApiKey
  | ProxyError::ApiKeyExpired
  | ProxyError::ApiKeyDisabled

crates/aisix-proxy/src/passthrough_route.rs

@@ -352,10 +352,7 @@ pub async fn entry(
  status,
  elapsed,
  );
- crate::usage_attr::emit_error_usage_event(
- &state,
- &snapshot,
- "passthrough_route",
+ let mut event = crate::usage_attr::build_error_usage_event(
  "passthrough",
  &request_id,
  "",
@@ -364,6 +361,16 @@ pub async fn entry(
  error.kind(),
  &client,
  );
+ // The route matched before the pipeline failed, so a rejected
+ // request still attributes to it — an operator triaging 401s
+ // per route needs the name on the event, not just in the log.
+ event.passthrough_route_name = route_name.clone();
+ crate::usage_attr::emit_prepared_usage_event(
+ &state,
+ &snapshot,
+ "passthrough_route",
+ event,
+ );
  error.into_response()
  }
  }
@@ -917,7 +924,7 @@ async fn authenticate(
  .and_then(|v| v.to_str().ok())
  .map(|v| v.strip_prefix("Bearer ").unwrap_or(v).trim().to_string())
  .filter(|v| !v.is_empty())
- .ok_or(ProxyError::MissingAuth)?;
+ .ok_or_else(|| ProxyError::MissingRouteAuthHeader(name.to_string()))?;
  crate::auth::authenticate_token(state, &token, ctx).await
  }
  PassthroughAuthMode::Anonymous => {

crates/aisix-proxy/src/usage_attr.rs

@@ -354,6 +354,30 @@ pub(crate) fn emit_error_usage_event(
  error_class: &str,
  client: &ClientContext,
 ) {
+ let event = build_error_usage_event(
+ inbound_protocol,
+ request_id,
+ requested_model,
+ api_key_id,
+ status_code,
+ error_class,
+ client,
+ );
+ emit_prepared_usage_event(state, snap, label, event);
+}
+
+/// The [`emit_error_usage_event`] event without the emission, for a caller
+/// that attributes handler-specific fields (e.g. the passthrough route name)
+/// before handing it to [`emit_prepared_usage_event`].
+pub(crate) fn build_error_usage_event(
+ inbound_protocol: &'static str,
+ request_id: &str,
+ requested_model: &str,
+ api_key_id: &str,
+ status_code: u16,
+ error_class: &str,
+ client: &ClientContext,
+) -> UsageEvent {
  let mut event = UsageEvent {
  request_id: request_id.to_string(),
  occurred_at: chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Secs, true),
@@ -367,6 +391,15 @@ pub(crate) fn emit_error_usage_event(
  ..Default::default()
  };
  apply_jwt_identity(&mut event, client.jwt.as_ref());
+ event
+}
+
+pub(crate) fn emit_prepared_usage_event(
+ state: &ProxyState,
+ snap: &AisixSnapshot,
+ label: &'static str,
+ event: UsageEvent,
+) {
  state.usage_sink.try_emit(label, event.clone());
  let exporters = live_exporters(state, snap);
  state

schemas/resources/passthrough_route.schema.json

@@ -240,6 +240,78 @@
  ]
  }
  },
+ {
+ "if": {
+ "anyOf": [
+ {
+ "not": {
+ "required": [
+ "auth_mode"
+ ]
+ },
+ "title": "auth_mode omitted (defaults to gateway_key)"
+ },
+ {
+ "properties": {
+ "auth_mode": {
+ "enum": [
+ "gateway_key",
+ "anonymous"
+ ]
+ }
+ },
+ "required": [
+ "auth_mode"
+ ],
+ "title": "auth_mode: gateway_key or anonymous"
+ }
+ ]
+ },
+ "then": {
+ "not": {
+ "required": [
+ "auth_header_name"
+ ]
+ }
+ },
+ "title": "auth_header_name only in header_key mode"
+ },
+ {
+ "if": {
+ "anyOf": [
+ {
+ "not": {
+ "required": [
+ "auth_mode"
+ ]
+ },
+ "title": "auth_mode omitted (defaults to gateway_key)"
+ },
+ {
+ "properties": {
+ "auth_mode": {
+ "enum": [
+ "gateway_key",
+ "header_key"
+ ]
+ }
+ },
+ "required": [
+ "auth_mode"
+ ],
+ "title": "auth_mode: gateway_key or header_key"
+ }
+ ]
+ },
+ "then": {
+ "not": {
+ "required": [
+ "anonymous_key_id"
+ ]
+ }
+ },
+ "title": "anonymous_key_id only in anonymous mode"
+ },
  {
  "if": {
  "anyOf": [

tests/e2e/src/cases/passthrough-route-e2e.test.ts

@@ -281,6 +281,25 @@ describe("passthrough-route e2e: explicit routes, BYO credentials, 410 tombstone
  // …and the gateway's side-channel headers did not.
  expect(hit.headers["x-aisix-api-key"]).toBeUndefined();
  expect(hit.headers["x-aisix-user"]).toBeUndefined();
+
+ // Missing gateway key: the 401 must point at the route's configured
+ // header, not `Authorization` — on this route Authorization carries the
+ // caller's own upstream credential and is exactly the wrong thing to fix.
+ const noKey = await harnessRequest(`${app!.proxyUrl}/v1/chat/completions`, {
+ method: "POST",
+ headers: {
+ host: "ai-upstream.example.com",
+ authorization: "Bearer employee-official-token",
+ "content-type": "application/json",
+ },
+ body: JSON.stringify({ model: "gpt-4o", messages: [] }),
+ });
+ expect(noKey.statusCode).toBe(401);
+ const noKeyBody = (await noKey.body.json()) as {
+ error?: { message?: string };
+ };
+ expect(noKeyBody.error?.message).toContain("x-aisix-api-key");
+ expect(noKeyBody.error?.message).not.toContain("Authorization");
  });
 
  test("anonymous route binds the configured principal behind source_cidrs", async (ctx) => {

crates/aisix-core/src/models/passthrough_route.rs

@@ -379,6 +379,30 @@ pub fn passthrough_route_coupling() -> Value {
  }
  }
  },
+ // Cross-mode leftovers are configuration errors, not ignored
+ // fields: a companion outside its mode is never consulted, so a
+ // row carrying one is rejected rather than half-honored. The CP
+ // enforces the identical rule on create and patch.
+ {
+ "title": "auth_header_name only in header_key mode",
+ "if": {
+ "anyOf": [
+ { "title": "auth_mode omitted (defaults to gateway_key)", "not": { "required": ["auth_mode"] } },
+ { "title": "auth_mode: gateway_key or anonymous", "properties": { "auth_mode": { "enum": ["gateway_key", "anonymous"] } }, "required": ["auth_mode"] }
+ ]
+ },
+ "then": { "not": { "required": ["auth_header_name"] } }
+ },
+ {
+ "title": "anonymous_key_id only in anonymous mode",
+ "if": {
+ "anyOf": [
+ { "title": "auth_mode omitted (defaults to gateway_key)", "not": { "required": ["auth_mode"] } },
+ { "title": "auth_mode: gateway_key or header_key", "properties": { "auth_mode": { "enum": ["gateway_key", "header_key"] } }, "required": ["auth_mode"] }
+ ]
+ },
+ "then": { "not": { "required": ["anonymous_key_id"] } }
+ },
  // credential_mode couplings: inject needs a real ProviderKey id; a
  // forward_client route carrying one is a configuration error, not
  // an ignored field.
@@ -516,6 +540,39 @@ mod coupling_tests {
  assert!(validate_passthrough_route(&doc).is_err());
  }
 
+ #[test]
+ fn cross_mode_leftover_companions_are_rejected() {
+ // A companion outside its mode is never consulted at runtime, so
+ // both validators refuse the row instead of half-honoring it.
+ // auth_header_name without header_key (auth_mode absent = gateway_key).
+ let mut doc = base();
+ doc["auth_header_name"] = json!("x-aisix-api-key");
+ assert!(validate_passthrough_route(&doc).is_err());
+ assert!(validate_passthrough_route_lenient(&doc).is_err());
+ // anonymous_key_id on an explicit header_key route.
+ let doc = json!({
+ "name": "r", "path_prefix": "/p",
+ "target_url": "https://u.example", "provider_key_id": "pk",
+ "auth_mode": "header_key", "auth_header_name": "x-aisix-api-key",
+ "anonymous_key_id": "ak-1"
+ });
+ assert!(validate_passthrough_route(&doc).is_err());
+ // auth_header_name on an anonymous route.
+ let doc = json!({
+ "name": "r", "path_prefix": "/p",
+ "target_url": "https://u.example", "provider_key_id": "pk",
+ "auth_mode": "anonymous", "anonymous_key_id": "ak-1",
+ "source_cidrs": ["10.0.0.0/8"],
+ "auth_header_name": "x-aisix-api-key"
+ });
+ assert!(validate_passthrough_route(&doc).is_err());
+ // source_cidrs is deliberately NOT mode-coupled: an extra IP
+ // allowlist is honored on every mode.
+ let mut doc = base();
+ doc["source_cidrs"] = json!(["10.0.0.0/8"]);
+ assert!(validate_passthrough_route(&doc).is_ok());
+ }
+
  #[test]
  fn credential_bearing_header_slots_are_rejected() {
  for field in ["auth_header_name", "identity_header"] {

crates/aisix-obs/src/otlp_http_sink.rs

@@ -743,6 +743,16 @@ fn build_otlp_span(record: &SinkRecord, exporter_name: &str) -> Value {
  &event.client_user_agent,
  ));
  }
+ // End-user identity a passthrough route's `identity_header` extracted —
+ // the per-employee attribution of the forward-proxy scenario. Not gated
+ // on the protocol so a future handler that learns to populate it exports
+ // it without touching this sink.
+ if !event.client_identity.is_empty() {
+ attributes.push(attr_string_capped(
+ "aisix.client_identity",
+ &event.client_identity,
+ ));
+ }
  // JWT identity attribution (AISIX-Cloud#564): who the request ran as
  // when it authenticated with a JWT — the identity behind the (possibly
  // shared) api_key_id.
@@ -802,6 +812,14 @@ fn build_otlp_span(record: &SinkRecord, exporter_name: &str) -> Value {
  attributes.push(attr_string("aisix.mcp.server_name", &event.mcp_server_name));
  }
  }
+ "passthrough" => {
+ if !event.passthrough_route_name.is_empty() {
+ attributes.push(attr_string(
+ "aisix.passthrough.route_name",
+ &event.passthrough_route_name,
+ ));
+ }
+ }
  _ => {}
  }
  // Opt-in captured content (#519 B.2) — present ONLY on a record built by
@@ -841,6 +859,7 @@ fn operation_name(event: &UsageEvent) -> &'static str {
  match event.inbound_protocol.as_str() {
  "a2a" => "invoke_agent",
  "mcp" => "execute_tool",
+ "passthrough" => "passthrough",
  _ => "chat",
  }
 }
@@ -867,6 +886,9 @@ fn span_name(event: &UsageEvent) -> String {
  let target = match event.inbound_protocol.as_str() {
  "a2a" => &event.a2a_agent_name,
  "mcp" => &event.mcp_tool_name,
+ // A route name is a registered resource like an agent name, so it is
+ // operator-bounded — but it still passes the length cap below.
+ "passthrough" => &event.passthrough_route_name,
  _ => return "chat.completions".to_string(),
  };
  if target.is_empty() || target.len() > MAX_SPAN_NAME_TARGET {
@@ -1535,6 +1557,44 @@ mod tests {
  assert_eq!(string_at("aisix.a2a.task_state"), "working");
  }
 
+ #[test]
+ fn a_passthrough_relay_exports_route_and_identity_not_a_chat_span() {
+ // The passthrough handler emits usage events with
+ // `inbound_protocol = "passthrough"`; without the explicit branch a
+ // Copilot relay exported as a bare `chat.completions` span with the
+ // route and the device-injected end-user identity recorded nowhere.
+ let mut ev = sample_event();
+ ev.inbound_protocol = "passthrough".into();
+ ev.passthrough_route_name = "copilot-chat".into();
+ ev.client_identity = "alice@example.com".into();
+
+ let body = build_otlp_traces_payload(&ev, "test-exp");
+ let span = &body["resourceSpans"][0]["scopeSpans"][0]["spans"][0];
+ assert_eq!(span["name"], "passthrough copilot-chat");
+ let attrs = span["attributes"].as_array().unwrap();
+ let find = |k: &str| attrs.iter().find(|a| a["key"] == k);
+ let string_at = |k: &str| find(k).unwrap()["value"]["stringValue"].clone();
+ assert_eq!(string_at("gen_ai.operation.name"), "passthrough");
+ assert_eq!(string_at("aisix.passthrough.route_name"), "copilot-chat");
+ assert_eq!(string_at("aisix.client_identity"), "alice@example.com");
+ }
+
+ #[test]
+ fn client_identity_exports_without_a_protocol_gate() {
+ // The identity attribute must not depend on the passthrough branch:
+ // any handler that populates the field gets it exported.
+ let mut ev = sample_event();
+ ev.client_identity = "bob@example.com".into();
+ let body = build_otlp_traces_payload(&ev, "test-exp");
+ let span = &body["resourceSpans"][0]["scopeSpans"][0]["spans"][0];
+ let attrs = span["attributes"].as_array().unwrap();
+ let id = attrs
+ .iter()
+ .find(|a| a["key"] == "aisix.client_identity")
+ .unwrap();
+ assert_eq!(id["value"]["stringValue"], "bob@example.com");
+ }
+
  #[test]
  fn a_streamed_a2a_call_carries_its_event_count() {
  // A unary call has no count, and exporting a zero would read as "the

crates/aisix-proxy/src/attempt.rs

@@ -291,6 +291,7 @@ pub(crate) fn attempt_reached_upstream(err: &ProxyError) -> bool {
  ProxyError::Bridge(be) => be.reached_upstream(),
  ProxyError::ContentFiltered(_) => true,
  ProxyError::MissingAuth
+ | ProxyError::MissingRouteAuthHeader(_)
  | ProxyError::InvalidApiKey
  | ProxyError::ApiKeyExpired
  | ProxyError::ApiKeyDisabled

crates/aisix-proxy/src/error.rs

@@ -166,6 +166,13 @@ impl ErrorEnvelope {
 pub enum ProxyError {
  #[error("missing or malformed Authorization header")]
  MissingAuth,
+ /// A `header_key` passthrough route saw no gateway key in its configured
+ /// header. Named separately from [`ProxyError::MissingAuth`] because on
+ /// these routes `Authorization` deliberately carries the caller's own
+ /// upstream credential — telling the integrator to fix `Authorization`
+ /// points at exactly the wrong header.
+ #[error("missing or malformed {0} header (this route's gateway API key header)")]
+ MissingRouteAuthHeader(String),
  #[error("invalid API key")]
  InvalidApiKey,
  /// The presented key exists but its `expires_at` deadline has
@@ -336,7 +343,8 @@ pub(crate) fn guardrail_block_message(side: &str, guardrail_name: Option<&str>)
 impl ProxyError {
  pub fn status(&self) -> StatusCode {
  match self {
- ProxyError::MissingAuth
+ ProxyError::MissingRouteAuthHeader(_)
+ | ProxyError::MissingAuth
  | ProxyError::InvalidApiKey
  | ProxyError::ApiKeyExpired
  | ProxyError::ApiKeyDisabled
@@ -369,7 +377,8 @@ impl ProxyError {
 
  pub fn kind(&self) -> &'static str {
  match self {
- ProxyError::MissingAuth
+ ProxyError::MissingRouteAuthHeader(_)
+ | ProxyError::MissingAuth
  | ProxyError::InvalidApiKey
  | ProxyError::ApiKeyExpired
  | ProxyError::ApiKeyDisabled

crates/aisix-proxy/src/passthrough_route.rs

@@ -352,10 +352,7 @@ pub async fn entry(
  status,
  elapsed,
  );
- crate::usage_attr::emit_error_usage_event(
- &state,
- &snapshot,
- "passthrough_route",
+ let mut event = crate::usage_attr::build_error_usage_event(
  "passthrough",
  &request_id,
  "",
@@ -364,6 +361,16 @@ pub async fn entry(
  error.kind(),
  &client,
  );
+ // The route matched before the pipeline failed, so a rejected
+ // request still attributes to it — an operator triaging 401s
+ // per route needs the name on the event, not just in the log.
+ event.passthrough_route_name = route_name.clone();
+ crate::usage_attr::emit_prepared_usage_event(
+ &state,
+ &snapshot,
+ "passthrough_route",
+ event,
+ );
  error.into_response()
  }
  }
@@ -917,7 +924,7 @@ async fn authenticate(
  .and_then(|v| v.to_str().ok())
  .map(|v| v.strip_prefix("Bearer ").unwrap_or(v).trim().to_string())
  .filter(|v| !v.is_empty())
- .ok_or(ProxyError::MissingAuth)?;
+ .ok_or_else(|| ProxyError::MissingRouteAuthHeader(name.to_string()))?;
  crate::auth::authenticate_token(state, &token, ctx).await
  }
  PassthroughAuthMode::Anonymous => {

crates/aisix-proxy/src/usage_attr.rs

@@ -354,6 +354,30 @@ pub(crate) fn emit_error_usage_event(
  error_class: &str,
  client: &ClientContext,
 ) {
+ let event = build_error_usage_event(
+ inbound_protocol,
+ request_id,
+ requested_model,
+ api_key_id,
+ status_code,
+ error_class,
+ client,
+ );
+ emit_prepared_usage_event(state, snap, label, event);
+}
+
+/// The [`emit_error_usage_event`] event without the emission, for a caller
+/// that attributes handler-specific fields (e.g. the passthrough route name)
+/// before handing it to [`emit_prepared_usage_event`].
+pub(crate) fn build_error_usage_event(
+ inbound_protocol: &'static str,
+ request_id: &str,
+ requested_model: &str,
+ api_key_id: &str,
+ status_code: u16,
+ error_class: &str,
+ client: &ClientContext,
+) -> UsageEvent {
  let mut event = UsageEvent {
  request_id: request_id.to_string(),
  occurred_at: chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Secs, true),
@@ -367,6 +391,15 @@ pub(crate) fn emit_error_usage_event(
  ..Default::default()
  };
  apply_jwt_identity(&mut event, client.jwt.as_ref());
+ event
+}
+
+pub(crate) fn emit_prepared_usage_event(
+ state: &ProxyState,
+ snap: &AisixSnapshot,
+ label: &'static str,
+ event: UsageEvent,
+) {
  state.usage_sink.try_emit(label, event.clone());
  let exporters = live_exporters(state, snap);
  state

schemas/resources/passthrough_route.schema.json

@@ -240,6 +240,78 @@
  ]
  }
  },
+ {
+ "if": {
+ "anyOf": [
+ {
+ "not": {
+ "required": [
+ "auth_mode"
+ ]
+ },
+ "title": "auth_mode omitted (defaults to gateway_key)"
+ },
+ {
+ "properties": {
+ "auth_mode": {
+ "enum": [
+ "gateway_key",
+ "anonymous"
+ ]
+ }
+ },
+ "required": [
+ "auth_mode"
+ ],
+ "title": "auth_mode: gateway_key or anonymous"
+ }
+ ]
+ },
+ "then": {
+ "not": {
+ "required": [
+ "auth_header_name"
+ ]
+ }
+ },
+ "title": "auth_header_name only in header_key mode"
+ },
+ {
+ "if": {
+ "anyOf": [
+ {
+ "not": {
+ "required": [
+ "auth_mode"
+ ]
+ },
+ "title": "auth_mode omitted (defaults to gateway_key)"
+ },
+ {
+ "properties": {
+ "auth_mode": {
+ "enum": [
+ "gateway_key",
+ "header_key"
+ ]
+ }
+ },
+ "required": [
+ "auth_mode"
+ ],
+ "title": "auth_mode: gateway_key or header_key"
+ }
+ ]
+ },
+ "then": {
+ "not": {
+ "required": [
+ "anonymous_key_id"
+ ]
+ }
+ },
+ "title": "anonymous_key_id only in anonymous mode"
+ },
  {
  "if": {
  "anyOf": [

tests/e2e/src/cases/passthrough-route-e2e.test.ts

@@ -281,6 +281,25 @@ describe("passthrough-route e2e: explicit routes, BYO credentials, 410 tombstone
  // …and the gateway's side-channel headers did not.
  expect(hit.headers["x-aisix-api-key"]).toBeUndefined();
  expect(hit.headers["x-aisix-user"]).toBeUndefined();
+
+ // Missing gateway key: the 401 must point at the route's configured
+ // header, not `Authorization` — on this route Authorization carries the
+ // caller's own upstream credential and is exactly the wrong thing to fix.
+ const noKey = await harnessRequest(`${app!.proxyUrl}/v1/chat/completions`, {
+ method: "POST",
+ headers: {
+ host: "ai-upstream.example.com",
+ authorization: "Bearer employee-official-token",
+ "content-type": "application/json",
+ },
+ body: JSON.stringify({ model: "gpt-4o", messages: [] }),
+ });
+ expect(noKey.statusCode).toBe(401);
+ const noKeyBody = (await noKey.body.json()) as {
+ error?: { message?: string };
+ };
+ expect(noKeyBody.error?.message).toContain("x-aisix-api-key");
+ expect(noKeyBody.error?.message).not.toContain("Authorization");
  });
 
  test("anonymous route binds the configured principal behind source_cidrs", async (ctx) => {

crates/aisix-core/src/models/passthrough_route.rs

@@ -379,6 +379,30 @@ pub fn passthrough_route_coupling() -> Value {
  }
  }
  },
+ // Cross-mode leftovers are configuration errors, not ignored
+ // fields: a companion outside its mode is never consulted, so a
+ // row carrying one is rejected rather than half-honored. The CP
+ // enforces the identical rule on create and patch.
+ {
+ "title": "auth_header_name only in header_key mode",
+ "if": {
+ "anyOf": [
+ { "title": "auth_mode omitted (defaults to gateway_key)", "not": { "required": ["auth_mode"] } },
+ { "title": "auth_mode: gateway_key or anonymous", "properties": { "auth_mode": { "enum": ["gateway_key", "anonymous"] } }, "required": ["auth_mode"] }
+ ]
+ },
+ "then": { "not": { "required": ["auth_header_name"] } }
+ },
+ {
+ "title": "anonymous_key_id only in anonymous mode",
+ "if": {
+ "anyOf": [
+ { "title": "auth_mode omitted (defaults to gateway_key)", "not": { "required": ["auth_mode"] } },
+ { "title": "auth_mode: gateway_key or header_key", "properties": { "auth_mode": { "enum": ["gateway_key", "header_key"] } }, "required": ["auth_mode"] }
+ ]
+ },
+ "then": { "not": { "required": ["anonymous_key_id"] } }
+ },
  // credential_mode couplings: inject needs a real ProviderKey id; a
  // forward_client route carrying one is a configuration error, not
  // an ignored field.
@@ -516,6 +540,39 @@ mod coupling_tests {
  assert!(validate_passthrough_route(&doc).is_err());
  }
 
+ #[test]
+ fn cross_mode_leftover_companions_are_rejected() {
+ // A companion outside its mode is never consulted at runtime, so
+ // both validators refuse the row instead of half-honoring it.
+ // auth_header_name without header_key (auth_mode absent = gateway_key).
+ let mut doc = base();
+ doc["auth_header_name"] = json!("x-aisix-api-key");
+ assert!(validate_passthrough_route(&doc).is_err());
+ assert!(validate_passthrough_route_lenient(&doc).is_err());
+ // anonymous_key_id on an explicit header_key route.
+ let doc = json!({
+ "name": "r", "path_prefix": "/p",
+ "target_url": "https://u.example", "provider_key_id": "pk",
+ "auth_mode": "header_key", "auth_header_name": "x-aisix-api-key",
+ "anonymous_key_id": "ak-1"
+ });
+ assert!(validate_passthrough_route(&doc).is_err());
+ // auth_header_name on an anonymous route.
+ let doc = json!({
+ "name": "r", "path_prefix": "/p",
+ "target_url": "https://u.example", "provider_key_id": "pk",
+ "auth_mode": "anonymous", "anonymous_key_id": "ak-1",
+ "source_cidrs": ["10.0.0.0/8"],
+ "auth_header_name": "x-aisix-api-key"
+ });
+ assert!(validate_passthrough_route(&doc).is_err());
+ // source_cidrs is deliberately NOT mode-coupled: an extra IP
+ // allowlist is honored on every mode.
+ let mut doc = base();
+ doc["source_cidrs"] = json!(["10.0.0.0/8"]);
+ assert!(validate_passthrough_route(&doc).is_ok());
+ }
+
  #[test]
  fn credential_bearing_header_slots_are_rejected() {
  for field in ["auth_header_name", "identity_header"] {

crates/aisix-obs/src/otlp_http_sink.rs

@@ -743,6 +743,16 @@ fn build_otlp_span(record: &SinkRecord, exporter_name: &str) -> Value {
  &event.client_user_agent,
  ));
  }
+ // End-user identity a passthrough route's `identity_header` extracted —
+ // the per-employee attribution of the forward-proxy scenario. Not gated
+ // on the protocol so a future handler that learns to populate it exports
+ // it without touching this sink.
+ if !event.client_identity.is_empty() {
+ attributes.push(attr_string_capped(
+ "aisix.client_identity",
+ &event.client_identity,
+ ));
+ }
  // JWT identity attribution (AISIX-Cloud#564): who the request ran as
  // when it authenticated with a JWT — the identity behind the (possibly
  // shared) api_key_id.
@@ -802,6 +812,14 @@ fn build_otlp_span(record: &SinkRecord, exporter_name: &str) -> Value {
  attributes.push(attr_string("aisix.mcp.server_name", &event.mcp_server_name));
  }
  }
+ "passthrough" => {
+ if !event.passthrough_route_name.is_empty() {
+ attributes.push(attr_string(
+ "aisix.passthrough.route_name",
+ &event.passthrough_route_name,
+ ));
+ }
+ }
  _ => {}
  }
  // Opt-in captured content (#519 B.2) — present ONLY on a record built by
@@ -841,6 +859,7 @@ fn operation_name(event: &UsageEvent) -> &'static str {
  match event.inbound_protocol.as_str() {
  "a2a" => "invoke_agent",
  "mcp" => "execute_tool",
+ "passthrough" => "passthrough",
  _ => "chat",
  }
 }
@@ -867,6 +886,9 @@ fn span_name(event: &UsageEvent) -> String {
  let target = match event.inbound_protocol.as_str() {
  "a2a" => &event.a2a_agent_name,
  "mcp" => &event.mcp_tool_name,
+ // A route name is a registered resource like an agent name, so it is
+ // operator-bounded — but it still passes the length cap below.
+ "passthrough" => &event.passthrough_route_name,
  _ => return "chat.completions".to_string(),
  };
  if target.is_empty() || target.len() > MAX_SPAN_NAME_TARGET {
@@ -1535,6 +1557,44 @@ mod tests {
  assert_eq!(string_at("aisix.a2a.task_state"), "working");
  }
 
+ #[test]
+ fn a_passthrough_relay_exports_route_and_identity_not_a_chat_span() {
+ // The passthrough handler emits usage events with
+ // `inbound_protocol = "passthrough"`; without the explicit branch a
+ // Copilot relay exported as a bare `chat.completions` span with the
+ // route and the device-injected end-user identity recorded nowhere.
+ let mut ev = sample_event();
+ ev.inbound_protocol = "passthrough".into();
+ ev.passthrough_route_name = "copilot-chat".into();
+ ev.client_identity = "alice@example.com".into();
+
+ let body = build_otlp_traces_payload(&ev, "test-exp");
+ let span = &body["resourceSpans"][0]["scopeSpans"][0]["spans"][0];
+ assert_eq!(span["name"], "passthrough copilot-chat");
+ let attrs = span["attributes"].as_array().unwrap();
+ let find = |k: &str| attrs.iter().find(|a| a["key"] == k);
+ let string_at = |k: &str| find(k).unwrap()["value"]["stringValue"].clone();
+ assert_eq!(string_at("gen_ai.operation.name"), "passthrough");
+ assert_eq!(string_at("aisix.passthrough.route_name"), "copilot-chat");
+ assert_eq!(string_at("aisix.client_identity"), "alice@example.com");
+ }
+
+ #[test]
+ fn client_identity_exports_without_a_protocol_gate() {
+ // The identity attribute must not depend on the passthrough branch:
+ // any handler that populates the field gets it exported.
+ let mut ev = sample_event();
+ ev.client_identity = "bob@example.com".into();
+ let body = build_otlp_traces_payload(&ev, "test-exp");
+ let span = &body["resourceSpans"][0]["scopeSpans"][0]["spans"][0];
+ let attrs = span["attributes"].as_array().unwrap();
+ let id = attrs
+ .iter()
+ .find(|a| a["key"] == "aisix.client_identity")
+ .unwrap();
+ assert_eq!(id["value"]["stringValue"], "bob@example.com");
+ }
+
  #[test]
  fn a_streamed_a2a_call_carries_its_event_count() {
  // A unary call has no count, and exporting a zero would read as "the

crates/aisix-proxy/src/attempt.rs

@@ -291,6 +291,7 @@ pub(crate) fn attempt_reached_upstream(err: &ProxyError) -> bool {
  ProxyError::Bridge(be) => be.reached_upstream(),
  ProxyError::ContentFiltered(_) => true,
  ProxyError::MissingAuth
+ | ProxyError::MissingRouteAuthHeader(_)
  | ProxyError::InvalidApiKey
  | ProxyError::ApiKeyExpired
  | ProxyError::ApiKeyDisabled

crates/aisix-proxy/src/error.rs

@@ -166,6 +166,13 @@ impl ErrorEnvelope {
 pub enum ProxyError {
  #[error("missing or malformed Authorization header")]
  MissingAuth,
+ /// A `header_key` passthrough route saw no gateway key in its configured
+ /// header. Named separately from [`ProxyError::MissingAuth`] because on
+ /// these routes `Authorization` deliberately carries the caller's own
+ /// upstream credential — telling the integrator to fix `Authorization`
+ /// points at exactly the wrong header.
+ #[error("missing or malformed {0} header (this route's gateway API key header)")]
+ MissingRouteAuthHeader(String),
  #[error("invalid API key")]
  InvalidApiKey,
  /// The presented key exists but its `expires_at` deadline has
@@ -336,7 +343,8 @@ pub(crate) fn guardrail_block_message(side: &str, guardrail_name: Option<&str>)
 impl ProxyError {
  pub fn status(&self) -> StatusCode {
  match self {
- ProxyError::MissingAuth
+ ProxyError::MissingRouteAuthHeader(_)
+ | ProxyError::MissingAuth
  | ProxyError::InvalidApiKey
  | ProxyError::ApiKeyExpired
  | ProxyError::ApiKeyDisabled
@@ -369,7 +377,8 @@ impl ProxyError {
 
  pub fn kind(&self) -> &'static str {
  match self {
- ProxyError::MissingAuth
+ ProxyError::MissingRouteAuthHeader(_)
+ | ProxyError::MissingAuth
  | ProxyError::InvalidApiKey
  | ProxyError::ApiKeyExpired
  | ProxyError::ApiKeyDisabled

crates/aisix-proxy/src/passthrough_route.rs

@@ -352,10 +352,7 @@ pub async fn entry(
  status,
  elapsed,
  );
- crate::usage_attr::emit_error_usage_event(
- &state,
- &snapshot,
- "passthrough_route",
+ let mut event = crate::usage_attr::build_error_usage_event(
  "passthrough",
  &request_id,
  "",
@@ -364,6 +361,16 @@ pub async fn entry(
  error.kind(),
  &client,
  );
+ // The route matched before the pipeline failed, so a rejected
+ // request still attributes to it — an operator triaging 401s
+ // per route needs the name on the event, not just in the log.
+ event.passthrough_route_name = route_name.clone();
+ crate::usage_attr::emit_prepared_usage_event(
+ &state,
+ &snapshot,
+ "passthrough_route",
+ event,
+ );
  error.into_response()
  }
  }
@@ -917,7 +924,7 @@ async fn authenticate(
  .and_then(|v| v.to_str().ok())
  .map(|v| v.strip_prefix("Bearer ").unwrap_or(v).trim().to_string())
  .filter(|v| !v.is_empty())
- .ok_or(ProxyError::MissingAuth)?;
+ .ok_or_else(|| ProxyError::MissingRouteAuthHeader(name.to_string()))?;
  crate::auth::authenticate_token(state, &token, ctx).await
  }
  PassthroughAuthMode::Anonymous => {

crates/aisix-proxy/src/usage_attr.rs

@@ -354,6 +354,30 @@ pub(crate) fn emit_error_usage_event(
  error_class: &str,
  client: &ClientContext,
 ) {
+ let event = build_error_usage_event(
+ inbound_protocol,
+ request_id,
+ requested_model,
+ api_key_id,
+ status_code,
+ error_class,
+ client,
+ );
+ emit_prepared_usage_event(state, snap, label, event);
+}
+
+/// The [`emit_error_usage_event`] event without the emission, for a caller
+/// that attributes handler-specific fields (e.g. the passthrough route name)
+/// before handing it to [`emit_prepared_usage_event`].
+pub(crate) fn build_error_usage_event(
+ inbound_protocol: &'static str,
+ request_id: &str,
+ requested_model: &str,
+ api_key_id: &str,
+ status_code: u16,
+ error_class: &str,
+ client: &ClientContext,
+) -> UsageEvent {
  let mut event = UsageEvent {
  request_id: request_id.to_string(),
  occurred_at: chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Secs, true),
@@ -367,6 +391,15 @@ pub(crate) fn emit_error_usage_event(
  ..Default::default()
  };
  apply_jwt_identity(&mut event, client.jwt.as_ref());
+ event
+}
+
+pub(crate) fn emit_prepared_usage_event(
+ state: &ProxyState,
+ snap: &AisixSnapshot,
+ label: &'static str,
+ event: UsageEvent,
+) {
  state.usage_sink.try_emit(label, event.clone());
  let exporters = live_exporters(state, snap);
  state

schemas/resources/passthrough_route.schema.json

@@ -240,6 +240,78 @@
  ]
  }
  },
+ {
+ "if": {
+ "anyOf": [
+ {
+ "not": {
+ "required": [
+ "auth_mode"
+ ]
+ },
+ "title": "auth_mode omitted (defaults to gateway_key)"
+ },
+ {
+ "properties": {
+ "auth_mode": {
+ "enum": [
+ "gateway_key",
+ "anonymous"
+ ]
+ }
+ },
+ "required": [
+ "auth_mode"
+ ],
+ "title": "auth_mode: gateway_key or anonymous"
+ }
+ ]
+ },
+ "then": {
+ "not": {
+ "required": [
+ "auth_header_name"
+ ]
+ }
+ },
+ "title": "auth_header_name only in header_key mode"
+ },
+ {
+ "if": {
+ "anyOf": [
+ {
+ "not": {
+ "required": [
+ "auth_mode"
+ ]
+ },
+ "title": "auth_mode omitted (defaults to gateway_key)"
+ },
+ {
+ "properties": {
+ "auth_mode": {
+ "enum": [
+ "gateway_key",
+ "header_key"
+ ]
+ }
+ },
+ "required": [
+ "auth_mode"
+ ],
+ "title": "auth_mode: gateway_key or header_key"
+ }
+ ]
+ },
+ "then": {
+ "not": {
+ "required": [
+ "anonymous_key_id"
+ ]
+ }
+ },
+ "title": "anonymous_key_id only in anonymous mode"
+ },
  {
  "if": {
  "anyOf": [

tests/e2e/src/cases/passthrough-route-e2e.test.ts

@@ -281,6 +281,25 @@ describe("passthrough-route e2e: explicit routes, BYO credentials, 410 tombstone
  // …and the gateway's side-channel headers did not.
  expect(hit.headers["x-aisix-api-key"]).toBeUndefined();
  expect(hit.headers["x-aisix-user"]).toBeUndefined();
+
+ // Missing gateway key: the 401 must point at the route's configured
+ // header, not `Authorization` — on this route Authorization carries the
+ // caller's own upstream credential and is exactly the wrong thing to fix.
+ const noKey = await harnessRequest(`${app!.proxyUrl}/v1/chat/completions`, {
+ method: "POST",
+ headers: {
+ host: "ai-upstream.example.com",
+ authorization: "Bearer employee-official-token",
+ "content-type": "application/json",
+ },
+ body: JSON.stringify({ model: "gpt-4o", messages: [] }),
+ });
+ expect(noKey.statusCode).toBe(401);
+ const noKeyBody = (await noKey.body.json()) as {
+ error?: { message?: string };
+ };
+ expect(noKeyBody.error?.message).toContain("x-aisix-api-key");
+ expect(noKeyBody.error?.message).not.toContain("Authorization");
  });
 
  test("anonymous route binds the configured principal behind source_cidrs", async (ctx) => {

crates/aisix-core/src/models/passthrough_route.rs

@@ -379,6 +379,30 @@ pub fn passthrough_route_coupling() -> Value {
  }
  }
  },
+ // Cross-mode leftovers are configuration errors, not ignored
+ // fields: a companion outside its mode is never consulted, so a
+ // row carrying one is rejected rather than half-honored. The CP
+ // enforces the identical rule on create and patch.
+ {
+ "title": "auth_header_name only in header_key mode",
+ "if": {
+ "anyOf": [
+ { "title": "auth_mode omitted (defaults to gateway_key)", "not": { "required": ["auth_mode"] } },
+ { "title": "auth_mode: gateway_key or anonymous", "properties": { "auth_mode": { "enum": ["gateway_key", "anonymous"] } }, "required": ["auth_mode"] }
+ ]
+ },
+ "then": { "not": { "required": ["auth_header_name"] } }
+ },
+ {
+ "title": "anonymous_key_id only in anonymous mode",
+ "if": {
+ "anyOf": [
+ { "title": "auth_mode omitted (defaults to gateway_key)", "not": { "required": ["auth_mode"] } },
+ { "title": "auth_mode: gateway_key or header_key", "properties": { "auth_mode": { "enum": ["gateway_key", "header_key"] } }, "required": ["auth_mode"] }
+ ]
+ },
+ "then": { "not": { "required": ["anonymous_key_id"] } }
+ },
  // credential_mode couplings: inject needs a real ProviderKey id; a
  // forward_client route carrying one is a configuration error, not
  // an ignored field.
@@ -516,6 +540,39 @@ mod coupling_tests {
  assert!(validate_passthrough_route(&doc).is_err());
  }
 
+ #[test]
+ fn cross_mode_leftover_companions_are_rejected() {
+ // A companion outside its mode is never consulted at runtime, so
+ // both validators refuse the row instead of half-honoring it.
+ // auth_header_name without header_key (auth_mode absent = gateway_key).
+ let mut doc = base();
+ doc["auth_header_name"] = json!("x-aisix-api-key");
+ assert!(validate_passthrough_route(&doc).is_err());
+ assert!(validate_passthrough_route_lenient(&doc).is_err());
+ // anonymous_key_id on an explicit header_key route.
+ let doc = json!({
+ "name": "r", "path_prefix": "/p",
+ "target_url": "https://u.example", "provider_key_id": "pk",
+ "auth_mode": "header_key", "auth_header_name": "x-aisix-api-key",
+ "anonymous_key_id": "ak-1"
+ });
+ assert!(validate_passthrough_route(&doc).is_err());
+ // auth_header_name on an anonymous route.
+ let doc = json!({
+ "name": "r", "path_prefix": "/p",
+ "target_url": "https://u.example", "provider_key_id": "pk",
+ "auth_mode": "anonymous", "anonymous_key_id": "ak-1",
+ "source_cidrs": ["10.0.0.0/8"],
+ "auth_header_name": "x-aisix-api-key"
+ });
+ assert!(validate_passthrough_route(&doc).is_err());
+ // source_cidrs is deliberately NOT mode-coupled: an extra IP
+ // allowlist is honored on every mode.
+ let mut doc = base();
+ doc["source_cidrs"] = json!(["10.0.0.0/8"]);
+ assert!(validate_passthrough_route(&doc).is_ok());
+ }
+
  #[test]
  fn credential_bearing_header_slots_are_rejected() {
  for field in ["auth_header_name", "identity_header"] {

crates/aisix-obs/src/otlp_http_sink.rs

@@ -743,6 +743,16 @@ fn build_otlp_span(record: &SinkRecord, exporter_name: &str) -> Value {
  &event.client_user_agent,
  ));
  }
+ // End-user identity a passthrough route's `identity_header` extracted —
+ // the per-employee attribution of the forward-proxy scenario. Not gated
+ // on the protocol so a future handler that learns to populate it exports
+ // it without touching this sink.
+ if !event.client_identity.is_empty() {
+ attributes.push(attr_string_capped(
+ "aisix.client_identity",
+ &event.client_identity,
+ ));
+ }
  // JWT identity attribution (AISIX-Cloud#564): who the request ran as
  // when it authenticated with a JWT — the identity behind the (possibly
  // shared) api_key_id.
@@ -802,6 +812,14 @@ fn build_otlp_span(record: &SinkRecord, exporter_name: &str) -> Value {
  attributes.push(attr_string("aisix.mcp.server_name", &event.mcp_server_name));
  }
  }
+ "passthrough" => {
+ if !event.passthrough_route_name.is_empty() {
+ attributes.push(attr_string(
+ "aisix.passthrough.route_name",
+ &event.passthrough_route_name,
+ ));
+ }
+ }
  _ => {}
  }
  // Opt-in captured content (#519 B.2) — present ONLY on a record built by
@@ -841,6 +859,7 @@ fn operation_name(event: &UsageEvent) -> &'static str {
  match event.inbound_protocol.as_str() {
  "a2a" => "invoke_agent",
  "mcp" => "execute_tool",
+ "passthrough" => "passthrough",
  _ => "chat",
  }
 }
@@ -867,6 +886,9 @@ fn span_name(event: &UsageEvent) -> String {
  let target = match event.inbound_protocol.as_str() {
  "a2a" => &event.a2a_agent_name,
  "mcp" => &event.mcp_tool_name,
+ // A route name is a registered resource like an agent name, so it is
+ // operator-bounded — but it still passes the length cap below.
+ "passthrough" => &event.passthrough_route_name,
  _ => return "chat.completions".to_string(),
  };
  if target.is_empty() || target.len() > MAX_SPAN_NAME_TARGET {
@@ -1535,6 +1557,44 @@ mod tests {
  assert_eq!(string_at("aisix.a2a.task_state"), "working");
  }
 
+ #[test]
+ fn a_passthrough_relay_exports_route_and_identity_not_a_chat_span() {
+ // The passthrough handler emits usage events with
+ // `inbound_protocol = "passthrough"`; without the explicit branch a
+ // Copilot relay exported as a bare `chat.completions` span with the
+ // route and the device-injected end-user identity recorded nowhere.
+ let mut ev = sample_event();
+ ev.inbound_protocol = "passthrough".into();
+ ev.passthrough_route_name = "copilot-chat".into();
+ ev.client_identity = "alice@example.com".into();
+
+ let body = build_otlp_traces_payload(&ev, "test-exp");
+ let span = &body["resourceSpans"][0]["scopeSpans"][0]["spans"][0];
+ assert_eq!(span["name"], "passthrough copilot-chat");
+ let attrs = span["attributes"].as_array().unwrap();
+ let find = |k: &str| attrs.iter().find(|a| a["key"] == k);
+ let string_at = |k: &str| find(k).unwrap()["value"]["stringValue"].clone();
+ assert_eq!(string_at("gen_ai.operation.name"), "passthrough");
+ assert_eq!(string_at("aisix.passthrough.route_name"), "copilot-chat");
+ assert_eq!(string_at("aisix.client_identity"), "alice@example.com");
+ }
+
+ #[test]
+ fn client_identity_exports_without_a_protocol_gate() {
+ // The identity attribute must not depend on the passthrough branch:
+ // any handler that populates the field gets it exported.
+ let mut ev = sample_event();
+ ev.client_identity = "bob@example.com".into();
+ let body = build_otlp_traces_payload(&ev, "test-exp");
+ let span = &body["resourceSpans"][0]["scopeSpans"][0]["spans"][0];
+ let attrs = span["attributes"].as_array().unwrap();
+ let id = attrs
+ .iter()
+ .find(|a| a["key"] == "aisix.client_identity")
+ .unwrap();
+ assert_eq!(id["value"]["stringValue"], "bob@example.com");
+ }
+
  #[test]
  fn a_streamed_a2a_call_carries_its_event_count() {
  // A unary call has no count, and exporting a zero would read as "the

crates/aisix-proxy/src/attempt.rs

@@ -291,6 +291,7 @@ pub(crate) fn attempt_reached_upstream(err: &ProxyError) -> bool {
  ProxyError::Bridge(be) => be.reached_upstream(),
  ProxyError::ContentFiltered(_) => true,
  ProxyError::MissingAuth
+ | ProxyError::MissingRouteAuthHeader(_)
  | ProxyError::InvalidApiKey
  | ProxyError::ApiKeyExpired
  | ProxyError::ApiKeyDisabled

crates/aisix-proxy/src/error.rs

@@ -166,6 +166,13 @@ impl ErrorEnvelope {
 pub enum ProxyError {
  #[error("missing or malformed Authorization header")]
  MissingAuth,
+ /// A `header_key` passthrough route saw no gateway key in its configured
+ /// header. Named separately from [`ProxyError::MissingAuth`] because on
+ /// these routes `Authorization` deliberately carries the caller's own
+ /// upstream credential — telling the integrator to fix `Authorization`
+ /// points at exactly the wrong header.
+ #[error("missing or malformed {0} header (this route's gateway API key header)")]
+ MissingRouteAuthHeader(String),
  #[error("invalid API key")]
  InvalidApiKey,
  /// The presented key exists but its `expires_at` deadline has
@@ -336,7 +343,8 @@ pub(crate) fn guardrail_block_message(side: &str, guardrail_name: Option<&str>)
 impl ProxyError {
  pub fn status(&self) -> StatusCode {
  match self {
- ProxyError::MissingAuth
+ ProxyError::MissingRouteAuthHeader(_)
+ | ProxyError::MissingAuth
  | ProxyError::InvalidApiKey
  | ProxyError::ApiKeyExpired
  | ProxyError::ApiKeyDisabled
@@ -369,7 +377,8 @@ impl ProxyError {
 
  pub fn kind(&self) -> &'static str {
  match self {
- ProxyError::MissingAuth
+ ProxyError::MissingRouteAuthHeader(_)
+ | ProxyError::MissingAuth
  | ProxyError::InvalidApiKey
  | ProxyError::ApiKeyExpired
  | ProxyError::ApiKeyDisabled

crates/aisix-proxy/src/passthrough_route.rs

@@ -352,10 +352,7 @@ pub async fn entry(
  status,
  elapsed,
  );
- crate::usage_attr::emit_error_usage_event(
- &state,
- &snapshot,
- "passthrough_route",
+ let mut event = crate::usage_attr::build_error_usage_event(
  "passthrough",
  &request_id,
  "",
@@ -364,6 +361,16 @@ pub async fn entry(
  error.kind(),
  &client,
  );
+ // The route matched before the pipeline failed, so a rejected
+ // request still attributes to it — an operator triaging 401s
+ // per route needs the name on the event, not just in the log.
+ event.passthrough_route_name = route_name.clone();
+ crate::usage_attr::emit_prepared_usage_event(
+ &state,
+ &snapshot,
+ "passthrough_route",
+ event,
+ );
  error.into_response()
  }
  }
@@ -917,7 +924,7 @@ async fn authenticate(
  .and_then(|v| v.to_str().ok())
  .map(|v| v.strip_prefix("Bearer ").unwrap_or(v).trim().to_string())
  .filter(|v| !v.is_empty())
- .ok_or(ProxyError::MissingAuth)?;
+ .ok_or_else(|| ProxyError::MissingRouteAuthHeader(name.to_string()))?;
  crate::auth::authenticate_token(state, &token, ctx).await
  }
  PassthroughAuthMode::Anonymous => {

crates/aisix-proxy/src/usage_attr.rs

@@ -354,6 +354,30 @@ pub(crate) fn emit_error_usage_event(
  error_class: &str,
  client: &ClientContext,
 ) {
+ let event = build_error_usage_event(
+ inbound_protocol,
+ request_id,
+ requested_model,
+ api_key_id,
+ status_code,
+ error_class,
+ client,
+ );
+ emit_prepared_usage_event(state, snap, label, event);
+}
+
+/// The [`emit_error_usage_event`] event without the emission, for a caller
+/// that attributes handler-specific fields (e.g. the passthrough route name)
+/// before handing it to [`emit_prepared_usage_event`].
+pub(crate) fn build_error_usage_event(
+ inbound_protocol: &'static str,
+ request_id: &str,
+ requested_model: &str,
+ api_key_id: &str,
+ status_code: u16,
+ error_class: &str,
+ client: &ClientContext,
+) -> UsageEvent {
  let mut event = UsageEvent {
  request_id: request_id.to_string(),
  occurred_at: chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Secs, true),
@@ -367,6 +391,15 @@ pub(crate) fn emit_error_usage_event(
  ..Default::default()
  };
  apply_jwt_identity(&mut event, client.jwt.as_ref());
+ event
+}
+
+pub(crate) fn emit_prepared_usage_event(
+ state: &ProxyState,
+ snap: &AisixSnapshot,
+ label: &'static str,
+ event: UsageEvent,
+) {
  state.usage_sink.try_emit(label, event.clone());
  let exporters = live_exporters(state, snap);
  state

schemas/resources/passthrough_route.schema.json

@@ -240,6 +240,78 @@
  ]
  }
  },
+ {
+ "if": {
+ "anyOf": [
+ {
+ "not": {
+ "required": [
+ "auth_mode"
+ ]
+ },
+ "title": "auth_mode omitted (defaults to gateway_key)"
+ },
+ {
+ "properties": {
+ "auth_mode": {
+ "enum": [
+ "gateway_key",
+ "anonymous"
+ ]
+ }
+ },
+ "required": [
+ "auth_mode"
+ ],
+ "title": "auth_mode: gateway_key or anonymous"
+ }
+ ]
+ },
+ "then": {
+ "not": {
+ "required": [
+ "auth_header_name"
+ ]
+ }
+ },
+ "title": "auth_header_name only in header_key mode"
+ },
+ {
+ "if": {
+ "anyOf": [
+ {
+ "not": {
+ "required": [
+ "auth_mode"
+ ]
+ },
+ "title": "auth_mode omitted (defaults to gateway_key)"
+ },
+ {
+ "properties": {
+ "auth_mode": {
+ "enum": [
+ "gateway_key",
+ "header_key"
+ ]
+ }
+ },
+ "required": [
+ "auth_mode"
+ ],
+ "title": "auth_mode: gateway_key or header_key"
+ }
+ ]
+ },
+ "then": {
+ "not": {
+ "required": [
+ "anonymous_key_id"
+ ]
+ }
+ },
+ "title": "anonymous_key_id only in anonymous mode"
+ },
  {
  "if": {
  "anyOf": [

tests/e2e/src/cases/passthrough-route-e2e.test.ts

@@ -281,6 +281,25 @@ describe("passthrough-route e2e: explicit routes, BYO credentials, 410 tombstone
  // …and the gateway's side-channel headers did not.
  expect(hit.headers["x-aisix-api-key"]).toBeUndefined();
  expect(hit.headers["x-aisix-user"]).toBeUndefined();
+
+ // Missing gateway key: the 401 must point at the route's configured
+ // header, not `Authorization` — on this route Authorization carries the
+ // caller's own upstream credential and is exactly the wrong thing to fix.
+ const noKey = await harnessRequest(`${app!.proxyUrl}/v1/chat/completions`, {
+ method: "POST",
+ headers: {
+ host: "ai-upstream.example.com",
+ authorization: "Bearer employee-official-token",
+ "content-type": "application/json",
+ },
+ body: JSON.stringify({ model: "gpt-4o", messages: [] }),
+ });
+ expect(noKey.statusCode).toBe(401);
+ const noKeyBody = (await noKey.body.json()) as {
+ error?: { message?: string };
+ };
+ expect(noKeyBody.error?.message).toContain("x-aisix-api-key");
+ expect(noKeyBody.error?.message).not.toContain("Authorization");
  });
 
  test("anonymous route binds the configured principal behind source_cidrs", async (ctx) => {

crates/aisix-core/src/models/passthrough_route.rs

@@ -379,6 +379,30 @@ pub fn passthrough_route_coupling() -> Value {
  }
  }
  },
+ // Cross-mode leftovers are configuration errors, not ignored
+ // fields: a companion outside its mode is never consulted, so a
+ // row carrying one is rejected rather than half-honored. The CP
+ // enforces the identical rule on create and patch.
+ {
+ "title": "auth_header_name only in header_key mode",
+ "if": {
+ "anyOf": [
+ { "title": "auth_mode omitted (defaults to gateway_key)", "not": { "required": ["auth_mode"] } },
+ { "title": "auth_mode: gateway_key or anonymous", "properties": { "auth_mode": { "enum": ["gateway_key", "anonymous"] } }, "required": ["auth_mode"] }
+ ]
+ },
+ "then": { "not": { "required": ["auth_header_name"] } }
+ },
+ {
+ "title": "anonymous_key_id only in anonymous mode",
+ "if": {
+ "anyOf": [
+ { "title": "auth_mode omitted (defaults to gateway_key)", "not": { "required": ["auth_mode"] } },
+ { "title": "auth_mode: gateway_key or header_key", "properties": { "auth_mode": { "enum": ["gateway_key", "header_key"] } }, "required": ["auth_mode"] }
+ ]
+ },
+ "then": { "not": { "required": ["anonymous_key_id"] } }
+ },
  // credential_mode couplings: inject needs a real ProviderKey id; a
  // forward_client route carrying one is a configuration error, not
  // an ignored field.
@@ -516,6 +540,39 @@ mod coupling_tests {
  assert!(validate_passthrough_route(&doc).is_err());
  }
 
+ #[test]
+ fn cross_mode_leftover_companions_are_rejected() {
+ // A companion outside its mode is never consulted at runtime, so
+ // both validators refuse the row instead of half-honoring it.
+ // auth_header_name without header_key (auth_mode absent = gateway_key).
+ let mut doc = base();
+ doc["auth_header_name"] = json!("x-aisix-api-key");
+ assert!(validate_passthrough_route(&doc).is_err());
+ assert!(validate_passthrough_route_lenient(&doc).is_err());
+ // anonymous_key_id on an explicit header_key route.
+ let doc = json!({
+ "name": "r", "path_prefix": "/p",
+ "target_url": "https://u.example", "provider_key_id": "pk",
+ "auth_mode": "header_key", "auth_header_name": "x-aisix-api-key",
+ "anonymous_key_id": "ak-1"
+ });
+ assert!(validate_passthrough_route(&doc).is_err());
+ // auth_header_name on an anonymous route.
+ let doc = json!({
+ "name": "r", "path_prefix": "/p",
+ "target_url": "https://u.example", "provider_key_id": "pk",
+ "auth_mode": "anonymous", "anonymous_key_id": "ak-1",
+ "source_cidrs": ["10.0.0.0/8"],
+ "auth_header_name": "x-aisix-api-key"
+ });
+ assert!(validate_passthrough_route(&doc).is_err());
+ // source_cidrs is deliberately NOT mode-coupled: an extra IP
+ // allowlist is honored on every mode.
+ let mut doc = base();
+ doc["source_cidrs"] = json!(["10.0.0.0/8"]);
+ assert!(validate_passthrough_route(&doc).is_ok());
+ }
+
  #[test]
  fn credential_bearing_header_slots_are_rejected() {
  for field in ["auth_header_name", "identity_header"] {

crates/aisix-obs/src/otlp_http_sink.rs

@@ -743,6 +743,16 @@ fn build_otlp_span(record: &SinkRecord, exporter_name: &str) -> Value {
  &event.client_user_agent,
  ));
  }
+ // End-user identity a passthrough route's `identity_header` extracted —
+ // the per-employee attribution of the forward-proxy scenario. Not gated
+ // on the protocol so a future handler that learns to populate it exports
+ // it without touching this sink.
+ if !event.client_identity.is_empty() {
+ attributes.push(attr_string_capped(
+ "aisix.client_identity",
+ &event.client_identity,
+ ));
+ }
  // JWT identity attribution (AISIX-Cloud#564): who the request ran as
  // when it authenticated with a JWT — the identity behind the (possibly
  // shared) api_key_id.
@@ -802,6 +812,14 @@ fn build_otlp_span(record: &SinkRecord, exporter_name: &str) -> Value {
  attributes.push(attr_string("aisix.mcp.server_name", &event.mcp_server_name));
  }
  }
+ "passthrough" => {
+ if !event.passthrough_route_name.is_empty() {
+ attributes.push(attr_string(
+ "aisix.passthrough.route_name",
+ &event.passthrough_route_name,
+ ));
+ }
+ }
  _ => {}
  }
  // Opt-in captured content (#519 B.2) — present ONLY on a record built by
@@ -841,6 +859,7 @@ fn operation_name(event: &UsageEvent) -> &'static str {
  match event.inbound_protocol.as_str() {
  "a2a" => "invoke_agent",
  "mcp" => "execute_tool",
+ "passthrough" => "passthrough",
  _ => "chat",
  }
 }
@@ -867,6 +886,9 @@ fn span_name(event: &UsageEvent) -> String {
  let target = match event.inbound_protocol.as_str() {
  "a2a" => &event.a2a_agent_name,
  "mcp" => &event.mcp_tool_name,
+ // A route name is a registered resource like an agent name, so it is
+ // operator-bounded — but it still passes the length cap below.
+ "passthrough" => &event.passthrough_route_name,
  _ => return "chat.completions".to_string(),
  };
  if target.is_empty() || target.len() > MAX_SPAN_NAME_TARGET {
@@ -1535,6 +1557,44 @@ mod tests {
  assert_eq!(string_at("aisix.a2a.task_state"), "working");
  }
 
+ #[test]
+ fn a_passthrough_relay_exports_route_and_identity_not_a_chat_span() {
+ // The passthrough handler emits usage events with
+ // `inbound_protocol = "passthrough"`; without the explicit branch a
+ // Copilot relay exported as a bare `chat.completions` span with the
+ // route and the device-injected end-user identity recorded nowhere.
+ let mut ev = sample_event();
+ ev.inbound_protocol = "passthrough".into();
+ ev.passthrough_route_name = "copilot-chat".into();
+ ev.client_identity = "alice@example.com".into();
+
+ let body = build_otlp_traces_payload(&ev, "test-exp");
+ let span = &body["resourceSpans"][0]["scopeSpans"][0]["spans"][0];
+ assert_eq!(span["name"], "passthrough copilot-chat");
+ let attrs = span["attributes"].as_array().unwrap();
+ let find = |k: &str| attrs.iter().find(|a| a["key"] == k);
+ let string_at = |k: &str| find(k).unwrap()["value"]["stringValue"].clone();
+ assert_eq!(string_at("gen_ai.operation.name"), "passthrough");
+ assert_eq!(string_at("aisix.passthrough.route_name"), "copilot-chat");
+ assert_eq!(string_at("aisix.client_identity"), "alice@example.com");
+ }
+
+ #[test]
+ fn client_identity_exports_without_a_protocol_gate() {
+ // The identity attribute must not depend on the passthrough branch:
+ // any handler that populates the field gets it exported.
+ let mut ev = sample_event();
+ ev.client_identity = "bob@example.com".into();
+ let body = build_otlp_traces_payload(&ev, "test-exp");
+ let span = &body["resourceSpans"][0]["scopeSpans"][0]["spans"][0];
+ let attrs = span["attributes"].as_array().unwrap();
+ let id = attrs
+ .iter()
+ .find(|a| a["key"] == "aisix.client_identity")
+ .unwrap();
+ assert_eq!(id["value"]["stringValue"], "bob@example.com");
+ }
+
  #[test]
  fn a_streamed_a2a_call_carries_its_event_count() {
  // A unary call has no count, and exporting a zero would read as "the

crates/aisix-proxy/src/attempt.rs

@@ -291,6 +291,7 @@ pub(crate) fn attempt_reached_upstream(err: &ProxyError) -> bool {
  ProxyError::Bridge(be) => be.reached_upstream(),
  ProxyError::ContentFiltered(_) => true,
  ProxyError::MissingAuth
+ | ProxyError::MissingRouteAuthHeader(_)
  | ProxyError::InvalidApiKey
  | ProxyError::ApiKeyExpired
  | ProxyError::ApiKeyDisabled

crates/aisix-proxy/src/error.rs

@@ -166,6 +166,13 @@ impl ErrorEnvelope {
 pub enum ProxyError {
  #[error("missing or malformed Authorization header")]
  MissingAuth,
+ /// A `header_key` passthrough route saw no gateway key in its configured
+ /// header. Named separately from [`ProxyError::MissingAuth`] because on
+ /// these routes `Authorization` deliberately carries the caller's own
+ /// upstream credential — telling the integrator to fix `Authorization`
+ /// points at exactly the wrong header.
+ #[error("missing or malformed {0} header (this route's gateway API key header)")]
+ MissingRouteAuthHeader(String),
  #[error("invalid API key")]
  InvalidApiKey,
  /// The presented key exists but its `expires_at` deadline has
@@ -336,7 +343,8 @@ pub(crate) fn guardrail_block_message(side: &str, guardrail_name: Option<&str>)
 impl ProxyError {
  pub fn status(&self) -> StatusCode {
  match self {
- ProxyError::MissingAuth
+ ProxyError::MissingRouteAuthHeader(_)
+ | ProxyError::MissingAuth
  | ProxyError::InvalidApiKey
  | ProxyError::ApiKeyExpired
  | ProxyError::ApiKeyDisabled
@@ -369,7 +377,8 @@ impl ProxyError {
 
  pub fn kind(&self) -> &'static str {
  match self {
- ProxyError::MissingAuth
+ ProxyError::MissingRouteAuthHeader(_)
+ | ProxyError::MissingAuth
  | ProxyError::InvalidApiKey
  | ProxyError::ApiKeyExpired
  | ProxyError::ApiKeyDisabled

crates/aisix-proxy/src/passthrough_route.rs

@@ -352,10 +352,7 @@ pub async fn entry(
  status,
  elapsed,
  );
- crate::usage_attr::emit_error_usage_event(
- &state,
- &snapshot,
- "passthrough_route",
+ let mut event = crate::usage_attr::build_error_usage_event(
  "passthrough",
  &request_id,
  "",
@@ -364,6 +361,16 @@ pub async fn entry(
  error.kind(),
  &client,
  );
+ // The route matched before the pipeline failed, so a rejected
+ // request still attributes to it — an operator triaging 401s
+ // per route needs the name on the event, not just in the log.
+ event.passthrough_route_name = route_name.clone();
+ crate::usage_attr::emit_prepared_usage_event(
+ &state,
+ &snapshot,
+ "passthrough_route",
+ event,
+ );
  error.into_response()
  }
  }
@@ -917,7 +924,7 @@ async fn authenticate(
  .and_then(|v| v.to_str().ok())
  .map(|v| v.strip_prefix("Bearer ").unwrap_or(v).trim().to_string())
  .filter(|v| !v.is_empty())
- .ok_or(ProxyError::MissingAuth)?;
+ .ok_or_else(|| ProxyError::MissingRouteAuthHeader(name.to_string()))?;
  crate::auth::authenticate_token(state, &token, ctx).await
  }
  PassthroughAuthMode::Anonymous => {

crates/aisix-proxy/src/usage_attr.rs

@@ -354,6 +354,30 @@ pub(crate) fn emit_error_usage_event(
  error_class: &str,
  client: &ClientContext,
 ) {
+ let event = build_error_usage_event(
+ inbound_protocol,
+ request_id,
+ requested_model,
+ api_key_id,
+ status_code,
+ error_class,
+ client,
+ );
+ emit_prepared_usage_event(state, snap, label, event);
+}
+
+/// The [`emit_error_usage_event`] event without the emission, for a caller
+/// that attributes handler-specific fields (e.g. the passthrough route name)
+/// before handing it to [`emit_prepared_usage_event`].
+pub(crate) fn build_error_usage_event(
+ inbound_protocol: &'static str,
+ request_id: &str,
+ requested_model: &str,
+ api_key_id: &str,
+ status_code: u16,
+ error_class: &str,
+ client: &ClientContext,
+) -> UsageEvent {
  let mut event = UsageEvent {
  request_id: request_id.to_string(),
  occurred_at: chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Secs, true),
@@ -367,6 +391,15 @@ pub(crate) fn emit_error_usage_event(
  ..Default::default()
  };
  apply_jwt_identity(&mut event, client.jwt.as_ref());
+ event
+}
+
+pub(crate) fn emit_prepared_usage_event(
+ state: &ProxyState,
+ snap: &AisixSnapshot,
+ label: &'static str,
+ event: UsageEvent,
+) {
  state.usage_sink.try_emit(label, event.clone());
  let exporters = live_exporters(state, snap);
  state

schemas/resources/passthrough_route.schema.json

@@ -240,6 +240,78 @@
  ]
  }
  },
+ {
+ "if": {
+ "anyOf": [
+ {
+ "not": {
+ "required": [
+ "auth_mode"
+ ]
+ },
+ "title": "auth_mode omitted (defaults to gateway_key)"
+ },
+ {
+ "properties": {
+ "auth_mode": {
+ "enum": [
+ "gateway_key",
+ "anonymous"
+ ]
+ }
+ },
+ "required": [
+ "auth_mode"
+ ],
+ "title": "auth_mode: gateway_key or anonymous"
+ }
+ ]
+ },
+ "then": {
+ "not": {
+ "required": [
+ "auth_header_name"
+ ]
+ }
+ },
+ "title": "auth_header_name only in header_key mode"
+ },
+ {
+ "if": {
+ "anyOf": [
+ {
+ "not": {
+ "required": [
+ "auth_mode"
+ ]
+ },
+ "title": "auth_mode omitted (defaults to gateway_key)"
+ },
+ {
+ "properties": {
+ "auth_mode": {
+ "enum": [
+ "gateway_key",
+ "header_key"
+ ]
+ }
+ },
+ "required": [
+ "auth_mode"
+ ],
+ "title": "auth_mode: gateway_key or header_key"
+ }
+ ]
+ },
+ "then": {
+ "not": {
+ "required": [
+ "anonymous_key_id"
+ ]
+ }
+ },
+ "title": "anonymous_key_id only in anonymous mode"
+ },
  {
  "if": {
  "anyOf": [

tests/e2e/src/cases/passthrough-route-e2e.test.ts

@@ -281,6 +281,25 @@ describe("passthrough-route e2e: explicit routes, BYO credentials, 410 tombstone
  // …and the gateway's side-channel headers did not.
  expect(hit.headers["x-aisix-api-key"]).toBeUndefined();
  expect(hit.headers["x-aisix-user"]).toBeUndefined();
+
+ // Missing gateway key: the 401 must point at the route's configured
+ // header, not `Authorization` — on this route Authorization carries the
+ // caller's own upstream credential and is exactly the wrong thing to fix.
+ const noKey = await harnessRequest(`${app!.proxyUrl}/v1/chat/completions`, {
+ method: "POST",
+ headers: {
+ host: "ai-upstream.example.com",
+ authorization: "Bearer employee-official-token",
+ "content-type": "application/json",
+ },
+ body: JSON.stringify({ model: "gpt-4o", messages: [] }),
+ });
+ expect(noKey.statusCode).toBe(401);
+ const noKeyBody = (await noKey.body.json()) as {
+ error?: { message?: string };
+ };
+ expect(noKeyBody.error?.message).toContain("x-aisix-api-key");
+ expect(noKeyBody.error?.message).not.toContain("Authorization");
  });
 
  test("anonymous route binds the configured principal behind source_cidrs", async (ctx) => {