Let API callers supply a token for gr.OAuthToken endpoints

[abidlabs]

This PR lets API callers supply a token for gr.OAuthToken endpoints. Previously, gr.OAuthToken is only ever populated from the OAuth session cookie, so it is always None for an API caller — there's no browser and no session. Any app whose function takes one therefore cannot be driven programmatically at all. This is not specific to gr.Workflow; a plain gr.Interface shows it. It surfaced through a deployed workflow, whose model nodes reached Inference Providers with no token and failed with Sign in with your HF account to use this model.

Why the body, not a header

gradio_client already forwards token= as x-hf-authorization, but I confirmed against a real Space that HF's proxy strips x-hf-* — the app only receives x-ip-token, an opaque JWT whose user claim is encrypted and which is rejected by both whoami ("Invalid user token") and Inference Providers. A custom header like x-gradio-token does survive, but that's undocumented infra behaviour that could change silently and would present as "OAuth randomly stopped working."

So the token travels in the request body as a reserved oauth_token field. Because it rides beside data rather than in it:

• it never becomes a positional argument and never appears in an endpoint's parameter schema, so no existing call signature changes;
• it can't be captured by flagging or cached examples, which only see component values;
• it works from curl and any other client with no client-side support at all.

A token only goes where the app asked for it

get_api_info now reports oauth_token: "required" | "optional" per endpoint, derived from the function signature, and the client consults that before including the field. An app can't collect tokens from calls that had no reason to carry one, and view_api() says plainly which endpoints act on the caller's behalf:

 - predict(api_name="/report") -> value_1
    Acts on your behalf: this endpoint takes your Hugging Face token (optional).
    Pass it with Client(..., oauth_token=...) to grant it.

oauth_token= is deliberately separate from token=: the latter only authenticates you to the app, so accessing a private Space no longer implies handing its code an act-as-you credential. It is never inferred from a locally saved token — if you don't pass it, nothing is granted.

Verified

Against the real OAuth Space gradio-tests/test-calculator-1 (/report takes a gr.OAuthToken, /calculator doesn't):

call	result
oauth_token= set, /report	user:<name> — usable token arrived
oauth_token= set, /calculator	6 — token not sent
oauth_token= unset, /report	none
curl with {"data":[],"oauth_token":"..."}	token arrived

[gradio-pr-bot]

🪼 branch checks and previews

•	Name	Status	URL
	Spaces	ready!	Spaces preview
	Website	ready!	Website preview
	Storybook	ready!	Storybook preview
🦄	Changes	detected!	Details

---

Install Gradio from this PR

pip install https://huggingface.co/buckets/gradio/pypi-previews/resolve/7811ad0bd07403fa9951696787af44f98a2b5730/gradio-6.20.0-py3-none-any.whl

Install Gradio Python Client from this PR

pip install "gradio-client @ git+https://github.com/gradio-app/gradio@7811ad0bd07403fa9951696787af44f98a2b5730#subdirectory=client/python"

Import Gradio JS Client from this PR via CDN

import { Client } from "https://huggingface.co/buckets/gradio/npm-previews/resolve/7811ad0bd07403fa9951696787af44f98a2b5730/browser.js";

[gradio-pr-bot]

🦄 change detected

This Pull Request includes changes to the following packages.

Package	Version
@gradio/client	minor
gradio	minor
gradio_client	minor

---

• oauth: let API callers supply a token for endpoints that take a gr.OAuthToken, via oauth_token on the Python and JS clients — sent only to endpoints that declare they need one

---

Something isn't right?

• Maintainers can change the version label to modify the version bump.
• If the bot has failed to detect any changes, or if this pull request needs to update multiple packages to different versions or requires a more comprehensive changelog entry, maintainers can update the changelog file directly.

[Copilot]

Pull request overview

This PR enables programmatic (non-browser) API callers to supply a Hugging Face user token to Gradio endpoints whose functions accept gr.OAuthToken, by carrying the token in a reserved oauth_token request-body field and only sending it to endpoints that declare they accept it.

Changes:

• Backend: plumbs an optional oauth_token field through predict request models and injects it into special_args() as an OAuthToken when present.
• API introspection: reports per-endpoint oauth_token: "required" | "optional" so callers can see which endpoints act on their behalf.
• Python client + test: adds Client(..., oauth_token=...), selectively includes the field per endpoint, and adds a real-space e2e test.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
test/test_oauth_api_access.py	Flaky e2e test verifying body-carried oauth_token reaches only endpoints that declare gr.OAuthToken.
gradio/utils.py	Adds helper to detect whether an endpoint takes gr.OAuthToken and whether it’s optional/required.
gradio/routes.py	Threads oauth_token from /call/v2 request bodies into PredictBody.
gradio/route_utils.py	Wraps body oauth_token into an OAuthToken object and passes it into Blocks.process_api().
gradio/data_classes.py	Extends request body models and API info typing to include oauth_token.
gradio/blocks.py	Propagates an oauth_token parameter through function calling and exposes requirement in get_api_info().
client/python/gradio_client/client.py	Adds oauth_token= to Client, surfaces it in view_api(), and includes it in request bodies when appropriate.
.changeset/shy-tokens-arrive.md	Announces minor releases for gradio and gradio_client with the new feature.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[abidlabs]

Fixed the first half: the scan now looks only at parameter annotations, so a function that returns an OAuthToken is no longer reported as one that receives it.

On the second half — missing OAuthToken | None — that one already worked. Optional[X] and PEP 604 X | None compare equal at runtime, so the single hint == Optional[OAuthToken] check matches both forms:

>>> (OAuthToken | None) == typing.Optional[OAuthToken]
True

Verified against both syntaxes before and after the change (def a(t: OAuthToken | None) and def b(t: Optional[OAuthToken]) both report optional), and special_args relies on the same equality today. I left the check as-is and added a comment noting it covers both, rather than adding a second branch that can never be reached.

[abidlabs]

Good catch — fixed in 7811ad0, though not quite as suggested, because a purely conditional pop reintroduces a different bug.

When this was conditional, sending oauth_token to an endpoint that declares none reached construct_args as an unknown argument and came back as a bare 500. Since oauth_token is a documented field of the request body, that is a rough edge. I had made the pop unconditional to fix it — which is the state you reviewed, and you are right that it then swallows the value of any endpoint whose own parameter is named oauth_token.

So it now distinguishes three cases rather than two:

oauth_token = None
if endpoint_info.get("oauth_token"):
    oauth_token = body.pop("oauth_token", None)
elif not any(p.get("parameter_name") == "oauth_token" for p in parameters_info):
    # Not this endpoint's to receive, and not one of its parameters
    # either, so drop it rather than report an unknown argument.
    body.pop("oauth_token", None)

Verified all five paths against a running app:

case	result
declares a token, token sent	token:hf_abc
declares a token, none sent	none
no token declared, token sent	echo (ignored, no 500)
own parameter named oauth_token, given	param:MINE
own parameter named oauth_token, omitted	param:orig

The last two are the regression you spotted; on the reviewed commit the first of them returned param:orig. Both are now covered by TestCurlEndpointWithOAuthToken in test/test_routes.py, and I confirmed the test fails with the unconditional pop restored.

[abidlabs]

The ordering half of this was already fixed in b756483 — **self.oauth_token_payload() now comes after **kwargs, so the computed payload wins rather than being overridden.

On the remaining half — a caller passing oauth_token= as an ordinary kwarg to reach an endpoint that declared none — I don't think that path is reachable, so I've left it as is rather than add a guard for it. _predict's kwargs is never populated from the public API: Client.submit() folds keyword arguments into positionals via construct_args and then invokes the endpoint with positional args only:

args = utils.construct_args(endpoint.parameters_info, args, kwargs)
...
future = self.executor.submit(copy_context().run, end_to_end_fn, *args)

construct_args rejects any name that is not a declared parameter, so the attempt fails before _predict is reached:

>>> client.predict(4, "add", 2, oauth_token="hf_SMUGGLE", api_name="/calculator")
TypeError: Parameter `oauth_token` is not a valid key-word argument.

make_predict has one call site (make_end_to_end_fn), which itself has one, so there is no other route in. Happy to add the defensive kwargs.pop if you'd still prefer the invariant enforced locally, but as written it would be dead code.

[abidlabs]

Already resolved — the docstring was rewritten while trimming this branch's comments and no longer opens with the stray quote:

def _get_oauth_token_requirement(self) -> str | None:
    """Returns "required", "optional", or None for this endpoint's gr.OAuthToken."""

[dawoodkhan82]

tested and lgtm!