Why is PyPI trusted publishing preferred over a long-lived API token in CI?

## Two ways to prove you may publish PyPI will not take an account password for an upload. It takes either an **API token** or a token obtained through **trusted publishing**, and the difference is the difference between a stored secret and a proven identity. ### The API token An API token is a bearer credential. You create it on the index, choose whether it is scoped to your whole account or to a single project, and from then on anything that holds the string can publish. twine sends it in the password field, paired with a fixed reserved username rather than your account name. Its properties are exactly the properties of a long-lived secret: * It must be **stored** somewhere — a CI secret store, a config file on disk, a password manager, and in practice several of those at once. * It does **not expire**. It is valid until a human revokes it, which means an unused token from a maintainer who left three years ago is still a live publishing credential. * It is **transferable**. It carries no information about who is using it or from where, so a copy taken from a build log, a compromised laptop or a misconfigured job works identically to the original. * Scoping is the only real mitigation, and it is coarse: project-scoped rather than account-scoped is a large improvement and should always be the default. ### Trusted publishing Trusted publishing inverts the flow. Instead of the CI job holding a secret, it holds nothing, and at publish time it asks its own platform for a **short-lived OIDC identity token**. That token is a signed assertion by the CI provider: this job is running in this repository, from this workflow file, in this environment, on this ref. The job posts it to PyPI. PyPI checks the signature, then checks the claims against a **trusted publisher** you configured on the project page — owner, repository, workflow filename, and optionally a deployment environment name. If it matches, PyPI mints a short-lived (minutes, not months) API token scoped to that one project and returns it, and twine or `uv publish` uses it for the upload. Minutes later it is worthless. Nothing long-lived is stored, so there is no secret to leak from a log, no rotation schedule, and no shared credential that outlives the person who created it. The credential is also *bound to a context*: it cannot be replayed from a laptop, and a workflow triggered by a pull request from a fork cannot obtain it, which closes the "attacker opens a pull request that publishes" path. ## The operational details that bite * **Set-up order.** The publisher is configured on PyPI *before* the first upload. For a project that does not exist yet, you configure a **pending publisher**, which claims the name on the first successful publish. Otherwise the very first release has a chicken-and-egg problem. * **The workflow filename is part of the identity.** Renaming or moving the publishing workflow breaks publishing until the publisher is updated. That is a feature — it is what makes the identity narrow — but it surprises people once. * **The job needs permission to mint an identity token.** On a provider that gates this, the publishing job must be granted the identity-token permission explicitly; without it the exchange fails before it reaches the index. * **Add an environment.** Configuring the publisher with a deployment environment lets you put approval rules and restricted branches in front of the only job that can publish, which narrows "anyone who can push to the repository can cut a release" to "anyone who can push through the protected release path". * **It does not cover everything.** A maintainer publishing from a workstation, or a CI system with no OIDC identity, still needs a token — make it project-scoped, and delete it when the pipeline takes over. ## What it does and does not solve Trusted publishing removes a *stored credential* from the equation. It does not settle the question of who may cause a publish: whoever can change the release workflow, or push the tag that triggers it, can still ship a release. The defence there is repository controls — protected branches and tags, required review on the workflow file, an environment gate — not the credential mechanism. And what to do once a bad release is out, or once a credential is believed compromised, is incident response, a separate discipline with its own playbook: revocation alone is not the whole answer, because anything the credential already published stays published. The one-line summary for an interview: **an API token is something you have and must protect forever; trusted publishing is something you are, proven at the moment of use and useless a few minutes later.**