PyPI API token scoping: automatic expiration for least‑privilege tokens

Answer

PyPI does not provide a built‑in expiration or time‑to‑live setting for project‑scoped API tokens; tokens are permanent until manually revoked.

Confirmed facts

• Project‑scoped tokens can be limited to a single package name.
• The PyPI web UI and API show no field for setting an expiration date.
• Revoking a token via the UI or the /user/tokens/ endpoint makes it invalid immediately.
• After revocation, any new upload attempt returns HTTP 401 Unauthorized (or 403 Forbidden).
• Packages already uploaded remain on PyPI; only future upload attempts are blocked.

Recommended steps for automated least‑privilege token lifecycle

1. Create a project‑scoped token for the target package (UI → Account Settings → API tokens → Add token, restrict to the project).
2. Store the token securely (e.g., secret manager, CI variable).
3. Schedule a periodic job (cron, CI workflow, or external scheduler) that calls the PyPI API to list the account’s tokens and delete the specific token after the desired TTL (e.g., 7 days). Example using curl with Basic Auth:

# List tokens to find the token ID
curl -s -u "__token__:$PYPI_PASSWORD" https://pypi.org/user/tokens/ |
  jq -r '.[] | select(.name=="my-project-token") | .id'

# Delete the token
curl -X DELETE -u "__token__:$PYPI_PASSWORD" \
  https://pypi.org/user/tokens//

If the deletion succeeds, subsequent uploads with that token will fail with 401.

Impact on ongoing deployments

• Only new upload attempts are affected; already‑published releases stay unchanged.
• Automated build systems will see an authentication error and should be configured to fetch a fresh token before the next upload.
• No notification is sent by PyPI; the consuming system must handle the 401 response and trigger token renewal.

Missing diagnostic detail

Do you have a reliable scheduled execution environment (cron, CI pipeline, or external scheduler) that can run the PyPI API deletion step? If not, the recommendation changes to using a short‑lived token generated just‑in‑time for each upload instead of a long‑lived token with scheduled revocation.