User, roles and the authentication, registration and security system in Kimai

A user can be part of a team, which can limit/extend the visibility of data. Access to certain features within Kimai are handled by the permission system, which is configurable through user roles.


There are two types of user avatars:

  • Auto generated avatar - a circle with colored background and username initials inside
  • Image URL - a user can configure an avatar URL in their profile (feature needs to be activated in System > Settings)

Deactivated users

If you uncheck the Active checkbox when editing the user profile and save:

  • the user will be hidden from the user listing => but you can display them again by using the search and selecting Both or no from the Active dropdown
  • the user won’t be displayed in most dropdowns and reports
  • the user cannot log in to Kimai

A user can be re-activated at any time. The logged-in user cannot deactivate his own profile.

If you want to see all deactivated accounts, please switch to the user listing (at System > Users) and choose Active = No in the filter dropdown.

System accounts

System accounts are users in Kimai, which are hidden in many places. They cannot be chosen from dropdowns, will be hidden in reports and more.

This setting is primarily meant to identify:

  • your Admin accounts (which should not be used for daily work)
  • API sync accounts

Username / User-ID

The username is a system-wide unique identifier which can be used for logging into the system and it will be included in exports.

It shouldn’t be changed without strong reasoning, but if you want to e.g. activate LDAP or SAML and see that you have to, then a System-Administrator can do so by editing the user profile (editing your own username is not possible).

The field is hidden by default, you have to double-click the user header to show it.

You should have a strong reasoning to change the username, e.g. think about API integrations and App logins.


The supervisor setting is used notifications, e.g. work-contract related features, approval workflows and such.

Staff number

The staff/account number appears in Exports and can be used to link users from your HR software to Kimai.

The search supports filtering by the fields:

  • role
  • state (active, deactivated, all)

Besides these filters, you can query for a free search term, which will be searched in the fields:

  • username
  • alias
  • title
  • email

Additionally, you can filter for custom fields by using a search phrase like location:homeoffice. This would find all entries with the custom field location matching the term homeoffice.

The search terms will be found within the full value, so searching for office would find:

  • I love working in my office
  • Office
  • This office is beautiful
  • Our offices are very noisy

Attention: checkboxes have the values 0 (not checked) and 1 (checked).

You can mix the search term and use multiple meta-field queries:

  • location:homeoffice hello - find all entries matching the search term hello with the custom field location matching the term homeoffice
  • location:homeoffice contract:fulltime - find all entries with the custom field combination: location matching homeoffice and contract matching fulltime
  • expired:0 finds all items whose expired checkbox is off

There are also special operators, which can be used in conjunction with custom fields (since Kimai 1.19.1):

  • The   empty string (e.g. location:) will find all entries whose value in the location field is either empty or not existing
  • The ~ search term (e.g. location:~) will find all entries that are missing the custom field (created before the field was created)
  • The * search term (e.g. location:*) will find all entries that have any value in the location field (basically the opposite of ~)

User registration

User registration is disabled by default, as most Kimai installations are available through the public internet.

If your Kimai installation is protected otherwise (e.g. internal network or other authentication mechanism) you can activate it through System > Settings. The self-registration is then available via a link in the login screen.

If someone registers a new account with email, username and password an confirmation email will be sent, including a link that needs to be clicked before the account will be activated. As this feature requires an email to work, you have to enable email support to use it.

Password reset

The reset password function is enabled by default, you can deactivate it through System > Settings.

A user can reach it via a link from the login screen. After entering username or email-address, an email with a confirmation link will be sent. This link needs to be clicked, afterwards the user can enter a new password.

You can configure two settings to influence the security:

  • Token lifetime (in seconds: 3600 = 1 hour) - the allowed time before a link expires
  • Retry pause (in seconds: 3600 = 1 hour) - the allowed time between multiple retries

As this feature requires an email to work, you have to enable email support to use it.


User can log in with a username or email. Administrators can activate different login methods (like LDAP or SAML) as well.

Your login works for at least one week in the Remember me mode. After coming back and being remembered you have access to all the following features:

  • view your own timesheet
  • start and stop new records
  • edit existing records

If you are an administrator, you will see all your allowed options in the menu, but will be redirected to a special confirmation/login form when you try to access them. This is a security feature to prevent abuse in case you forgot to log-out in public environments.

Two-Factor authentication

Kimai supports 2FA (Two-Factor) authentication via TOTP tokens.

The basic flows looks as this:

  • You scan a QR code in your Kimai user preferences screen with a TOTP supporting app
  • Your app will show you a confirmation code, which then needs to be entered in Kimai
  • If the code was correct, Kimai will enable 2FA for your account
  • The next time you log-in, you will have to open your app and enter the current confirmation code before entering Kimai

The 2FA-mode can be enabled per account, settings can be accessed by the user himself or by any Super-Admin.

The two-factor authentication can be enabled by all users, even for SAML accounts.


Cannot create user

If you try to create a user and see an error message like The email is already used or The username is already used it is very likely, that this account was deactivated in the past. Deactivation does not remove a user from Kimai, it just hides it from all views and listing.

You can reactivate the account by going to the User administration, open the search and choose the value Both or No for the search option Active. The resulting list will include all deactivated users which can be reactivated by editing them and checking the Active checkbox.

Recorded times are wrong

Please read the user preferences documentation especially the part about timezones.

The timezone is a user-specific setting and every user can have its own timezone setting. Don’t mix this up with the system specific configuration for new customers.