Skip to content

fix(openapi): declare authentication via securitySchemes instead of ignored header parameters - #716

Open
yingzhehu-TT wants to merge 3 commits into
Universal-Commerce-Protocol:mainfrom
yingzhehu-TT:fix/openapi-security-schemes
Open

yingzhehu-TT wants to merge 3 commits into
Universal-Commerce-Protocol:mainfrom
yingzhehu-TT:fix/openapi-security-schemes

Conversation

@yingzhehu-TT

@yingzhehu-TT yingzhehu-TT commented Aug 12, 2026 •

Copy link
Copy Markdown
Contributor

Closes #668

Depends on #914. Merge that first: it teaches the header_fields
docs macro to list headers declared through securitySchemes and content
maps. On its own this PR would remove Authorization, X-API-Key,
Content-Type and Accept from every REST binding's HTTP Headers table.

Summary

  • Declare authentication through components.securitySchemes and a
    document-level security requirement in every REST service definition:
    shopping, common and lodging.
  • Remove the authorization, x_api_key, content_type and accept header
    parameter definitions and every $ref to them.

Motivation

#668 reports that Authorization is declared as a header parameter, which
OpenAPI 3.1 requires implementations to ignore. The same clause covers two more
parameters the issue does not mention:

If in is "header" and the name field is "Accept", "Content-Type" or
"Authorization", the parameter definition SHALL be ignored.
— OpenAPI 3.1.0, Parameter Object

So tooling that follows the specification never sees the OAuth bearer
requirement, and no REST definition declares components.securitySchemes.
X-API-Key is not in the ignore list — generated code does keep it — but #668
asks for "securitySchemes that specify all supported types", so it moves too.

Since this PR was first opened, common/rest.openapi.json and
lodging/rest.openapi.json have been added on main with the same four header
parameters; both are covered here.

Design decisions

The schemes mirror the mechanisms the spec lists. The overview's
Authentication Mechanisms section names API Keys, OAuth 2.0, mTLS and HTTP
Message Signatures, and the cart, checkout and lodging booking REST bindings
state that "Authentication is optional and depends on business requirements".
Every mechanism OpenAPI can express is declared, as alternatives:

Mechanism security alternative
No authentication {}
API Keys via X-API-Key api_key — apiKey, header X-API-Key
OAuth 2.0 via Authorization: Bearer oauth2_bearer — http, bearer
Mutual TLS mutual_tls — mutualTLS
HTTP Message Signatures (RFC 9421) not expressible; stays as parameters

Keeping {} matters: every replaced parameter was required: false, so
omitting it would tighten the contract.

http/bearer rather than oauth2 with flows. An OAuth Flow Object
requires concrete tokenUrl / authorizationUrl values, and UCP has none to
give: platforms locate the authorization server at runtime through RFC 9728
protected-resource metadata and RFC 8414 server metadata, and it may sit on a
different origin. http/bearer states exactly what is true on the wire —
Authorization: Bearer <access_token> — without fabricating endpoints. The
header macro handles oauth2 too, so switching later would not affect the docs.

The order-event webhook keeps its own requirement. orderEvent is a
business-to-platform call, where a bearer token from the business's own
authorization server makes no sense, and OpenAPI 3.1 does not say whether
document-level security applies to webhooks. So it declares
security: [{}, {"api_key": []}] explicitly — the same optional X-API-Key it
had as a parameter.

Signature headers stay as parameters. Signature, Signature-Input and
Content-Digest are not in the ignore list, and OpenAPI 3.1 has no
security-scheme type for HTTP Message Signatures.

Corrections to the previous description

Several statements in the earlier description were wrong:

  • "No rendered-docs regression: main.py::method_fields explicitly skips
    in: header parameters ("Filter out headers (transport-specific)"), so
    removing them changes no generated table."
    method_fields does skip them,
    but header_fields renders exactly those parameters, so this change would
    have dropped four rows from every REST binding's header table. That is now
    handled by fix(docs): list headers declared through security and content maps #914, which this PR depends on.
  • "…the document-level security requirement applies to webhook operations
    too, so the webhook's authentication contract is preserved rather than
    dropped."
    OpenAPI 3.1 does not specify that, and if it did apply, the webhook
    would have gained an optional bearer alternative. The webhook now declares its
    own requirement, above.
  • "…the same four parameters with the same descriptions…", said of
    common/rest.openapi.json. It has the same four parameters, but its
    descriptions differ from shopping's.
  • "signatures.md states that platforms SHOULD sign requests and MAY
    use alternative mechanisms (API keys, OAuth, mTLS) instead."
    Its text is
    "Platforms SHOULD sign all requests when using HTTP Message Signatures.
    Alternative authentication mechanisms (API keys, OAuth, mTLS) may be used
    instead." — a lowercase "may", and a SHOULD conditional on using signatures.
    The basis for {} is now the REST bindings' own wording, above.
  • "Anything generated from these files — clients, validators, docs — silently
    drops the authentication contract."
    Only the ignored parameters are dropped;
    X-API-Key is not ignored and survives in generated code.

Scope

source/services/shopping/rest.openapi.json, common/rest.openapi.json and
lodging/rest.openapi.json, one commit each, with identical securitySchemes
and document-level security in all three. In common, this includes the
POST /ask operation added since the first revision.

permalink.openapi.json and handlers/tokenization/openapi.json declare no
authentication headers and are untouched. #897's food/rest.openapi.json is not
on main yet, so it is not changed here.

Validation

  • openapi-spec-validator, with info.version injected as
    hooks.py::_set_schema_version does at build time: shopping, common and
    lodging are all VALID OpenAPI 3.1.
  • ucp-schema lint source/ — 145 files checked, all passed. No $ref to a
    removed parameter remains anywhere under source/.
  • scripts/validate_examples.py --schema-base source/schemas/ — 398 passed,
    0 failed, 53 skipped.
  • With fix(docs): list headers declared through security and content maps #914 applied, across the six REST binding header tables: no header
    appears twice; all six list Authorization, X-API-Key and Accept, and all
    but get_order list Content-Type, since a GET has no request body. Those
    four rows now take their descriptions from the schemes and media types, and
    Content-Type / Accept move to the end of the table. mkdocs build --strict exits 0 under DOCS_MODE=spec and root.
  • Each edit was applied by line-level surgery guarded by a structural-equality
    assertion against an independently built target document, so nothing other
    than the intended removals and additions could change.

🤖 Generated with Claude Code

@google-cla

google-cla Bot commented Aug 12, 2026

Copy link
Copy Markdown

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

@damaz91 damaz91 added the status:needs-triage Signal that the PR is ready for human triage label Aug 12, 2026
@yingzhehu-TT

Copy link
Copy Markdown
Contributor Author

@googlebot I signed it!

@yingzhehu-TT
yingzhehu-TT force-pushed the fix/openapi-security-schemes branch from b03de9c to 3dd8837 Compare August 12, 2026 08:20
@damaz91 damaz91 added bug Something isn't working status:under-review gov:needs-tc-review Requires review and approval from the Technical Council and removed status:needs-triage Signal that the PR is ready for human triage labels Aug 12, 2026
@damaz91
damaz91 requested a review from jingyli August 12, 2026 09:13
@damaz91 damaz91 added status:stale-review Applied if a PR is waiting on a reviewer for too long and removed status:under-review labels Sep 2, 2026
@yingzhehu-TT
yingzhehu-TT force-pushed the fix/openapi-security-schemes branch from 3dd8837 to ff597f3 Compare September 3, 2026 18:25
@gsmith85 gsmith85 mentioned this pull request Sep 18, 2026
9 of 11 tasks
@damaz91 damaz91 added the area:shopping Issues and pull requests related to the Shopping vertical label Sep 24, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:shopping Issues and pull requests related to the Shopping vertical bug Something isn't working gov:needs-tc-review Requires review and approval from the Technical Council status:stale-review Applied if a PR is waiting on a reviewer for too long

Projects

Status: Triage / Unscheduled

Development

Successfully merging this pull request may close these issues.

[Bug]: Incorrect usage of "Authorization" header in OpenAPI 3.1.0

3 participants