Installation

devpi-tokens needs to be installed alongside devpi-server to enable authentication tokens.

On client machines the usage of tokens works without the plugin. The creation of tokens requires the devpi-tokens plugin to be installed alongside devpi-client. The plugin also adds several commands to inspect and derive tokens with restricted permissions.

You can install it with:

pip install devpi-tokens

There is no configuration needed as devpi-server and devpi-client will automatically discover the plugin through calling hooks using the setuptools entry points mechanism.

Motivation

The default authentication mechanism of devpi requires a username and password. With that the authenticated user has a fixed set of permissions. Especially for CI systems this is too inflexible. There is also the risk of leaking the password in log output and other sources.

With devpi-tokens it is possible to create additional authentication tokens per user. These tokens can have a limited set of permissions. It is impossible to modify any user data with a token.

It is possible to derive tokens from existing ones and limit the permission set even further without requiring contact with the server.

The plugin builds on macaroons.

Usage

The devpi-tokens plugin adds new commands when installed alongside devpi-client.

token-create

Create a new token for a user. By default the token is created in the scope of the current user. Administration users like root can create tokens for other users with the -u/--user option. The token has a default expiration date of one year, but that can be changed with the -e/--expires option. With the -a/--allowed, -i/--indexes and -p/--projects options the scope of the token can be further limited.

token-delete

Delete an existing token. Any derived tokens will be invalidated as well.

token-derive

Takes an existing token and derives a new one from it. This allows to limit the scope of the token further than the original one.

token-inspect

Show information about the given token. This includes any expiration times and permission limitations etc.

token-list

Show a list of tokens for a user from the server. This only shows initial tokens created with token-create. Derived tokens by definition can not be listed, as they do not require contact to the server.

token-login

Use a token for login with devpi-client. This is also useful to login longer than the default 10 hours by creating a token with a longer expiration time and no further restrictions. It is impossible to modify any user data when logged in like this, as tokens never have user manipulation permissions.

1.1.0 - 2025-06-25

• replace all usage of deprecated pylib

• add Python 3.12 and 3.13 support

• drop Python 3.7 support

• require at least devpi-server 6.10.0

1.0.1 - 2023-03-27

• fix leap year bug

1.0.0 - 2023-02-26

• add Python 3.10 support

• drop Python 3.6 support

• add not_before restriction

• support restrictions added by pypitoken in devpi-client 6.0.0

0.6.0 - Unreleased

• hide user permissions from help output, as they are disabled on the server side anyway

• allow token to be used with basic authentication as username and no password, or as password with no username

0.5.0 - Unreleased

• ask for confirmation when using unknown permissions

• add option to write generated token to a file

• show list of known devpi-server permissions in help

• show helpful error when delta dependency is missing

• fix timezone issue in expiration calculation

• show human readable expiration if possible

0.4.0 - Unreleased

• unify command naming by using prefix

• add token-delete command

• add token-derive command

• add token-list command

• allow root or users from --restrict-modify to create tokens for other users, and with no expiration

• add allowed restriction to tokens

• add expiration to tokens

• add indexes restriction to tokens

• add projects restriction to tokens

0.3.0 - Unreleased

• add inspect-token command

• verify login status when using token-login

0.2.0 - Unreleased

• use new hook and derived keys

0.1.0 - Unreleased