Docs: publishing > authentication > API tokens

[soxofaan]

https://hatch.pypa.io/latest/publish/#authentication mainly discusses user+password auth. Last week I used user+password auth to publish a project, and got this email from pypi:

... However, your account has two-factor authentication (2FA) enabled. In the near future, PyPI will begin prohibiting uploads using basic authentication for accounts with two-factor authentication enabled. Instead, we will require API tokens to be used.

I guess the Hatch documentation could use a bit of finetuning to cover API tokens better, because now it just mentions it as a recommendation for automated releases:

For automated releasing to PyPI, it is recommended that you use per-project API tokens.

Also relevant here: when one creates an API token, one has to pick the token's scope (all projects or an individual project). So that means that a developer might ends up with multiple "token passwords" (one for each projecct), which might not play well with the user/password caching mechanism described in the authentication docs.

[pitrou]

This relates to the broader discussion I opened here: https://discuss.python.org/t/2fa-usability-on-pypi-and-with-packaging-tools/38167/7

Here are some hatch-specific pain points IMHO:

• the docs do not mention 2FA or token-based authentication, leaving me in the dark
• hatch publish --help, similarly, did not help either, which left me dumbfounded
• the "credentials" prompt that hatch publish prints is not descriptive enough: is it expecting a password? something else? is it to safe to paste a secret in that prompt, or not?
• the __token__ special username should IMHO be considered an implementation detail of the PyPI REST API, not something that users should be facing, since it's relatively obscure

Ideally, when trying to upload using hatch publish, I should have the following user experience:

$ hatch publish
repository username: ...
repository password: ...

ERROR: two-factor authentication is enabled for username 'username' on repository 'URL'.
Please ensure an API token exists for this project and then use `hatch publish --token-auth`.

$ hatch publish --token-auth
API token for project: ...

[pitrou]

@ofek @jeanas

[lwasser]

hey @pitrou i'm workign through this now too - we are creating some tutorials on publishing using hatch. It seems like running

hatch publish -u __token__ works and then you simply provide the token Did that accomplish what you need? i'm thinking about adding a how-to on this to the hatch docs (just a small contribution) as it was unclear to me too how to ensure hatch authenticates via a token rather than a username.

i think for me what was confusing was when i ran hatch publish it asked for the username but then said [TOKEN] and i wasn't sure what that meant. so specityying -u __token__ seems to work

did that work for you?

[pitrou]

Hi @lwasser

hey @pitrou i'm workign through this now too - we are creating some tutorials on publishing using hatch.

Thanks for writing these tutorials, however it would be much nicer if the hatch UI was improved, or at least if its own docs included such instructions.

It seems like running hatch publish -u token works and then you simply provide the token Did that accomplish what you need?

Normally, yes, -u __token__ should work AFAIU. However, I've been using twine instead, and I haven't had the need to publish a package recently, so I can't concretely confirm.

[lwasser]

i hear you. i suspect a docs enhancement would be really helpful here and a lower lift. our tutorial work is totally separate from hatch i'm just noting painpoints and where docs might be useful in case i have bandwidth to help a bit here too! :)

[lorentzenchr]

I can confirm that -u __token__ worked for me. The first time I used hatch I used a username that then got cached. At some point I got annoyed to specify the __token__ each time and found out that it is possible to change some config file (can‘t remember where). Now, a simple hatch publish is enough.

Conclusion: Improving the already good documentation would be very helpful.

[ofek]

Documentation was improved in https://github.com/pypa/hatch/pull/789

Is there anything else that needs doing here?

[pitrou]

Thanks for this! It's certainly more descriptive and detailed, but I'm surprised it does not seem to explicitly mention two-factor auth anywhere (*). While API tokens are mentioned, it does not explicitly say how to use them with hatch (some guesswork from the user might suggest they work together with the __token__ special value, though).

Perhaps I'm overdoing this, so feel free to ignore ;-)

(*) a quick grep suggests the word "factor" does not appear once under https://github.com/pypa/hatch/tree/master/docs .

[ofek]

Sure, I can talk about that!