[Bug]: AgentCard securitySchemes APIKeySecurityScheme serializes in_ instead of in causing validation failure

[AnkurKumarShukla]

What happened?

Bug

When serving AgentCard from A2A server, the securitySchemes entry for an API key scheme is serialized with JSON key in_ instead of in.

This breaks A2A schema validation because the official schema expects:

• in (alias key in JSON)

but server returns:

• in_ (python field name)

Impact

Clients (host agents / A2A resolvers) that validate agent cards using the official schema fail with Pydantic validation error:

Field required: securitySchemes.x402.APIKeySecurityScheme.in
input: {"in_":"header", ...}

So paid/premium agents advertising payment schemes via securitySchemes become non-discoverable.

---

Reproduction Steps

1. Create an AgentCard that includes API Key security scheme.
2. Serve it via A2A server.
3. Fetch card:

curl http://localhost:<port>/.well-known/agent.json

"securitySchemes": {
  "x402": {
    "description": "...",
    "in_": "header",
    "name": "X-Payment",
    "type": "apiKey"
  }
}

Client attempts to parse using official schema, fails validation.

Eexected behaviour

The SDK should accept both "in" and "in_" as valid field names and map them internally
The SDK should use Pydantic's Field(alias="in") to allow the Python-safe in_ while validating against the JSON's in field
Documentation should clarify the correct field name to use

Relevant log output

2026-01-12 04:40:20,335 - INFO - _client.py:1740 - HTTP Request: GET http://localhost:10004/.well-known/agent.json "HTTP/1.1 200 OK"
2026-01-12 04:40:20,335 - INFO - client.py:95 - Successfully fetched agent card data from http://localhost:10004/.well-known/agent.json

ERROR: Failed to initialize connection for http://localhost:10004: JSON Error: Failed to validate agent card structure from http://localhost:10004/.well-known/agent.json: [
  {
    "type": "missing",
    "loc": ["securitySchemes", "x402", "APIKeySecurityScheme", "in"],
    "msg": "Field required",
    "input": {
      "description": "...",
      "in_": "header",
      "name": "X-Payment",
      "type": "apiKey"
    },
    "url": "https://errors.pydantic.dev/2.11/v/missing"
  },
  {
    "type": "missing",
    "loc": ["securitySchemes", "x402", "HTTPAuthSecurityScheme", "scheme"],
    "msg": "Field required",
    "input": {...},
    "url": "https://errors.pydantic.dev/2.11/v/missing"
  },
  {
    "type": "literal_error",
    "loc": ["securitySchemes", "x402", "HTTPAuthSecurityScheme", "type"],
    "msg": "Input should be 'http'",
    "input": "apiKey",
    "ctx": {"expected": "'http'"},
    "url": "https://errors.pydantic.dev/2.11/v/literal_error"
  },
  ...additional validation errors for other security scheme types...
]

Code of Conduct

• I agree to follow this project's Code of Conduct

[ryanaiagent]

Hi @AnkurKumarShukla, Thanks for the report! We’ve received the issue and have added it to our backlog for review. We’ll take a look as soon as we can.

[AnkurKumarShukla]

Hi maintainers 👋

I’d like to take ownership of this issue and submit a PR to fix the APIKeySecurityScheme.in serialization/validation mismatch.

---

Root cause

The apiKey security scheme uses the JSON field name in, but in Python models it is represented as in_ (keyword-safe).
Currently, the A2A server serializes the field as in_ instead of in, which breaks validation against the official schema.

---

Proposed fix

1) Schema/model fix (Pydantic aliasing)

Update APIKeySecurityScheme to use:

• in_: str = Field(alias="in")

Also configure the model to support alias population (accept both keys):

• populate_by_name=True

2) Server serialization

Ensure AgentCard JSON output uses aliases:

• model_dump(by_alias=True) (or equivalent)

This guarantees outgoing JSON uses in, not in_.

---

Compatibility goal

• Accept both "in" and "in_" from clients/servers (for backward compatibility).
• Always emit correct JSON using "in" according to the official schema.

---

Test plan

• Unit test: parsing security scheme should pass for both:
  • {"in": "header", ...}
  • {"in_": "header", ...}
• Integration test: /.well-known/agent.json should output "in" not "in_".
• Run schema validation against the official A2A schema.

---

If this plan looks good, please assign the issue to me — I can open a PR with the fix + tests.

Thanks!

[ryanaiagent]

Hi @AnkurKumarShukla , yes please proceed with the fix. Let us know once you have the PR ready.