TimeTagger library reference



Object that holds config values.

  • bind (str): the address and port to bind on. Default "".
  • datadir (str): the directory to store data. Default "~/_timetagger". The user db's are stored in datadir/users.
  • log_level (str): the log level for timetagger and asgineer (not the asgi server). Default "info".
  • credentials (str): login credentials for one or more users, in the form "user1:hash1,user2:hash2" where each hash is a salted hash (BCrypt) of the password. Used in the default startup script main.py. You can generate credentials with https://timetagger.app/cred.
  • proxy_auth_enabled (bool): enables authentication from a reverse proxy (for example Authelia). Default "False".
  • proxy_auth_trusted (str): list of trusted reverse proxy IPs with or without CIDR, in the form ",,,192.168/16". Default "".
  • proxy_auth_header (str): name of the proxy header which contains the username of the logged in user. Default "X-Remote-User".

The values can be configured using CLI arguments and environment variables. For CLI arguments, the following formats are supported:

python -m timetagger --datadir=~/timedata
python -m timetagger --datadir ~/timedata

For environment variable, the key is uppercase and prefixed:




Convert a username (e.g. email address) to the corresponding absolute filename.


Convert a (relative or absolute) filename to the corresponding username.

For the API server

async timetagger.server.authenticate(request)

Authenticate the user, returning (auth_info, db) if all is well. Raises AuthException if an authtoken is missing, not issued by us, does not match the seed (i.e. has been revoked), or has expired.

class timetagger.server.AuthException(msg)

Exception raised when authentication fails. You should catch this error and respond with 401 unauthorized.

async timetagger.server.api_handler_triage(request, path, auth_info, db)

The API handler that triages over the API options.

async timetagger.server.get_webtoken_unsafe(username, reset=False)

This function provides a webtoken that can be used to authenticate future requests. It is intended to bootstrap the authentication; the caller of this function is responsible for the request being authenticated in another way, for example:

  • Checking that the request is from localhost (for local use only).
  • Obtaining and validating a JWT from a trusted auth provider (e.g. Auth0).
  • Going through an OAuth workflow with a trusted provider (e.g Google or Github).
  • Implement an authenticate-via-email workflow.
  • Implement username/password authentication.

The provided webtoken expires in two weeks. It is recommended to use GET /api/v2/webtoken to get a fresh token once a day.

For the assets server

timetagger.server.md2html(text, template)
timetagger.server.create_assets_from_dir(dirname, template=None)

Get a dictionary of assets from a directory.


Enable the service worker 'sw.js', by giving it a cacheName based on a hash from all the assets.