docs(a2a): correct A2A auth header — Authorization: Bearer only, drop x-adcp-auth on A2A surface

.changeset/fix-a2a-bearer-auth-docs.md

@@ -0,0 +1,15 @@
+---
+---
+
+Corrects A2A authentication documentation to reflect the adcp 4.5.0
+per-leg header convention: A2A requires `Authorization: Bearer <token>`
+(RFC 6750) only; `x-adcp-auth` is a back-compat alias for MCP only.
+
+Changes:
+- `authentication.mdx`: splits "Protocol Configuration" to clarify
+  the MCP vs A2A header alias policy and adds a seller migration note
+  for the `a2a_header_name` knob.
+- `a2a-guide.mdx`: updates `A2AClient` init snippet from legacy
+  `apiKey:` field to `auth: { type: 'bearer', token: ... }`.
+- `a2a-guide.mdx`: adds `securitySchemes` / `security` to the sample
+  agent card so buyers see the correct `bearerAuth` declaration.

docs/building/by-layer/L0/a2a-guide.mdx

@@ -41,7 +41,10 @@ Examples below use **1.0 wire format** (no `kind` field, ProtoJSON enums). For a
 ```javascript
 const a2a = new A2AClient({
   endpoint: 'https://adcp.example.com/a2a',
-  apiKey: process.env.ADCP_API_KEY,
+  auth: {
+    type: 'bearer',
+    token: process.env.ADCP_API_KEY
+  },
   agent: {
     name: "AdCP Media Buyer",
     version: "1.0.0"
@@ -805,6 +808,13 @@ In 1.0, the top-level `url` and `protocolVersion` fields from v0.3 are replaced
   "name": "AdCP Media Buy Agent",
   "description": "AI-powered media buying agent",
   "version": "1.0.0",
+  "securitySchemes": {
+    "bearerAuth": {
+      "type": "http",
+      "scheme": "bearer"
+    }
+  },
+  "security": [{"bearerAuth": []}],
   "supportedInterfaces": [
     {
       "url": "https://sales.example.com/a2a/jsonrpc",

docs/building/by-layer/L2/authentication.mdx

@@ -128,7 +128,7 @@ The agency / A2A relay topology (brand → relay → seller) authenticates **und
 
 ## Protocol Configuration
 
-Both MCP and A2A protocols use the same authentication header. Configure your client with:
+Both MCP and A2A use `Authorization: Bearer <token>` ([RFC 6750 §2](https://www.rfc-editor.org/rfc/rfc6750#section-2)) as the authentication header. Configure your client with:
 
 ```json
 {
@@ -141,6 +141,15 @@ Both MCP and A2A protocols use the same authentication header. Configure your cl
 
 The client library handles adding the `Authorization: Bearer <token>` header to requests.
 
+**Header alias policy by leg.** The two protocol legs differ in what aliases they accept beyond the standard header:
+
+- **A2A** — `Authorization: Bearer <token>` only. The `x-adcp-auth` custom header is not recognized on the A2A surface; the seller's agent card declares a `bearerAuth` `HTTPAuthSecurityScheme` (see the [A2A guide — Agent Cards](/docs/building/by-layer/L0/a2a-guide#agent-cards)). Sending `x-adcp-auth` on the A2A leg returns HTTP 401.
+- **MCP** — `Authorization: Bearer <token>` (primary). `x-adcp-auth` is accepted as a back-compat alias for integrations predating adcp 4.5.0. New implementations should use the standard header on both legs.
+
+<Warning>
+**Sellers migrating to adcp 4.5.0.** If you previously configured `x-adcp-auth` as the A2A leg header via the `a2a_header_name` knob, verify that knob is set to the RFC 6750 default before updating your agent card to declare `bearerAuth` — buyers that have not yet migrated off the legacy header will otherwise receive HTTP 401.
+</Warning>
+
 ## MCP Client Configuration
 
 When using the MCP protocol, authentication is handled by the transport layer, not by adding HTTP headers manually.