API passwords will be removed - switch to API tokens now

General

13 Apr 2026

Kevin Papst

@kevinpapst

On 07 April 2024, we introduced API tokens in Kimai and deprecated API passwords.

Since then, both authentication methods have remained available to give administrators, users, and integration maintainers enough time to migrate. That transition period is now coming to an end.

API passwords will be removed after Q2 2026

Support for API passwords will be removed after Q2 2026, which means no later than July 2026.

If you are still using API passwords in scripts, tools, plugins, or custom integrations, you should update them now.

After the removal, API requests using the old authentication method will no longer work.

Who is affected?

This change affects everyone who still connects to the Kimai API with the old X-AUTH-* headers, for example in:

custom scripts
internal tools
desktop or mobile apps
automation platforms
external services
customer-specific integrations

It is especially relevant for administrators of self-hosted Kimai instances and technical contacts managing integrations for larger teams.

What changed?

Previously, Kimai API requests were authenticated with two custom headers:

X-AUTH-USER: your-username-or-email
X-AUTH-TOKEN: your-api-password

The API password had to be configured in the user profile.

You can still find that authentication method in the older documentation.

Today, Kimai uses the standard Bearer token authentication with a single header:

Authorization: Bearer xyz

Here, xyz is the API token generated for the account.

See the current documentation.

What will stop working?

Once support for API passwords is removed, integrations using this old format will no longer authenticate:

X-AUTH-USER: your-username-or-email
X-AUTH-TOKEN: your-api-password

To continue working, they must be changed to:

Authorization: Bearer your-api-token

Why you should migrate now

Migrating now helps you avoid broken integrations once support for API passwords is removed.

API tokens are the modern authentication method in Kimai and offer a cleaner setup:

one standard header instead of two custom headers
multiple tokens per user
optional expiration dates
better control and visibility

What administrators and support teams should do now

Please review all places where your Kimai API is used and identify integrations that still rely on API passwords.

Then:

update centrally managed integrations to use Authorization: Bearer
inform affected users and teams about the upcoming removal
ask users to create API tokens in their profile where required
test all critical integrations before the deadline

What your users need to do

Each user can generate API tokens in their Kimai user profile.

After creating a token, the integration they use must be updated and the new token must be added there instead of the old API password.

Many apps should already support API tokens, while older scripts and custom integrations may need to be adapted.

What to communicate to your users

If you support Kimai users in your organization, the message is simple:

API passwords are deprecated and will be removed after Q2 2026
old integrations using X-AUTH-USER and X-AUTH-TOKEN must be updated
users should create API tokens in their profile
integrations should use Authorization: Bearer

Need help?

Please check the current API documentation first.

If you maintain an integration for Kimai and are unsure how to migrate, feel free to get in touch.

Thanks for updating your integrations in time.

Menu