Text of peps.python.org › pep-0807 as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

PEP 807 – Index support for Trusted Publishing | peps.python.org

PEP 807 – Index support for Trusted Publishing PEP 807 – Index support for Trusted Publishing Author : William Woodruff <william at yossarian.net> Sponsor : Donald Stufft <donald at stufft.io> Discussions-To : Discourse thread Status : Draft Type : Standards Track Topic : Packaging Created : 19-Sep-2025 Post-History : 08-Aug-2025 , 29-Sep-2025 Table of Contents Abstract Motivation Rationale Specification Constraints Trusted Publishing Discovery Trusted Publishing Token Exchange Audience Retrieval Token Minting Feature Negotiation Security Implications Backwards Compatibility How To Teach This Rejected Ideas “Lateral” Discovery “Implicit” Discovery Footnotes Copyright Abstract This PEP proposes a standard mechanism through which arbitrary Python package indices can support “Trusted Publishing,” a misuse-resistant credential exchange scheme already implemented by the Python Package Index (PyPI).

The mechanism proposed in this PEP is designed to encapsulate PyPI’s existing implementation of Trusted Publishing, while allowing other indices to implement the same scheme in a manner that is discoverable by and interoperable with existing Python package uploading clients. Motivation “Trusted Publishing” is PyPI’s term of art for using the OpenID Connect (OIDC) standard to exchange a short-lived identity credential from a trusted third-party service (like a CI/CD or cloud provider) for a short-lived, minimally-scoped upload credential that can be used to publish to the index.

Trusted Publishing was originally designed and enabled on PyPI in 2023 as a non-standard (PyPI-specific) feature, much like the existing upload API . It has seen widespread adoption in that capacity: over one million files have been published to PyPI using a Trusted Publisher (as of September 2025), representing approximately one in every eight files uploaded to PyPI since becoming available. Additionally, PyPI’s design has inspired similar designs in the Rust (crates.io) , Ruby (RubyGems) , and JavaScript (npm) ecosystems.

The absence of a standard for Trusted Publishing presents a long-term impediment for adoption: third-party indices (i.e. those other than PyPI and TestPyPI) cannot easily implement Trusted Publishing without referencing PyPI’s unstandardized design. This in turn poses a long-term maturity risk similar to that of the unstandardized upload API: package upload clients (like Twine and uv ) must either accept behavioral differences between indices (leading to an accretion of hacks) or continue to reject non-PyPI implementations of Trusted Publishing.

Rationale The lack of an existing standard for Trusted Publishing is the primary rationale for this PEP. The design proposed in this PEP closely follows PyPI’s existing implementation, with an added layer of discovery that enables uploading clients to determine whether an arbitrary index supports Trusted Publishing without making PyPI-specific assumptions. The rationale for this design is as follows: The existing (unstandardized) implementation of Trusted Publishign on PyPI has a proven track record, and is already widely adopted in uploading tools.

A significant deviation from the existing design would introduce unnecessary compatibility risks. The discovery mechanism proposed in this PEP is designed to be consistent with existing standards for machine-to-machine protocols, namely RFC 8615 (Well-Known URIs). Additionally, this discovery mechanism is designed to allow multiple indices to be hosted under a single domain, which is a common topology for third-party index hosts.

In sum, the rationale for this PEP is to standardize PyPI’s existing interfaces and make them discoverable while allowing index hosts that don’t match PyPI’s topology to implement Trusted Publishing. Specification This PEP’s specification contains two parts: A discovery mechanism that package upload clients can use to determine whether an arbitrary Python package index host supports Trusted Publishing. A token exchange mechanism that package upload clients can use to exchange an identity credential for an upload credential.

Constraints Unless explicitly stated otherwise, the following constraints apply to all parts of this PEP’s specification: All URLs MUST have potentially trustworthy origins . In practice, this means that all URLs MUST use the https scheme, be some variant of a local loopback ( localhost , 127.0.0.1 , etc.), or otherwise be considered a priori trustworthy in the context of the interaction (e.g. an internal network). Uploading clients MUST reject any URLs that do not meet this constraint.

All server-supplied URLs (i.e. those in discovery responses) MUST have the same host subcomponent as the user-provided upload URL. Uploading clients MUST reject any URLs that do not meet this constraint. In practice, this means that a discovery request to https://upload.example.com/.well-known/pytp?discover={key} can only return URLs with the upload.example.com host. All client requests SHOULD have an Accept: application/vnd.pypi.pytp.v1+json header.

In the absence of an Accept header, the receiving server MUST behave as if this header were present. Receiving servers SHOULD respond with a 406 Not Acceptable status code if any other Accept header is present. Unless otherwise specified, all error (4xx and 5xx) responses from the server MUST use the RFC 9457 (Problem Details for HTTP APIs) format. In particular, the server MUST use the “Problem Details JSON Object” defined in Section 3 and SHOULD use the application/problem+json media type in its responses.

Trusted Publishing Discovery All Python package uploading is currently “endpoint driven,” in the sense uploading clients (like twine and uv ) are given an upload URL (and not merely a domain name). For example, to upload to PyPI, uploading clients are expected to connect to https://upload.pypi.org/legacy/ . The discovery mechanism proposed below takes advantage of this fact to allow single domains to advertise support for multiple indices (and their corresponding upload endpoints).

The discovery mechanism is as follows: The uploading client is given an upload URL, e.g. https://upload.example.com/legacy/ . The uploading client extracts the path component of the URL, as defined in RFC 3986 . If the path component is empty, the empty string should be used. For the above example, the path component is /legacy/ . The uploading client performs a query-safe URL encoding of the path component (i.e. percent-encoding as defined in RFC 3986 , including encoding of forward slashes and spaces), producing the discovery key .

For the above example, the discovery key is %2Flegacy%2F . [1] The uploading client constructs a discovery URL by taking the scheme and authority components (as defined in RFC 3986 ) of the upload URL and appending /.well-known/pytp as the path. Then, the uploading client appends the discovery key as the value of the discover query parameter. For the above example, the discovery URL is https://upload.example.com/.well-known/pytp?discover=%2Flegacy%2F .

The uploading client performs an HTTP GET request to the discovery URL. The server responds with a 200 OK status code and a body containing a JSON object if the index supports Trusted Publishing for the given upload URL. The JSON object MUST contain the following fields: audience-endpoint : a string containing the URL of the OIDC audience endpoint to be used during token exchange. token-mint-endpoint : a string containing the URL of the token minting endpoint to be used during token exchange.

Additionally, the JSON object MAY contain the following fields: features : an array of strings indicating optional features supported by the index’s Trusted Publishing implementation. The set of possible features is defined under feature negotiation . default-features : an array of strings indicating the default features used by the index’s Trusted Publishing implementation if a request does not explicitly s

The rest of this page is on the live site.