kimpanionMeet your companion

HERE TO HELP

A good place to start.

Connect Kimpanion to your Kimai account, find your timesheet and record your first entry on Mac, iPhone or iPad.

Connect your first account

You need an existing Kimai account, your server's HTTPS address and an API token for that account. Kimpanion does not create or host a Kimai server. If your organisation uses Kimai, ask its administrator for access. You can connect one account and manage its time entries and timers for free.

  1. Sign in to Kimai in your browser. Use your organisation's Kimai address and your usual Kimai login.
  2. Create an API token. Open your user menu or profile, then API access. Choose Create and, if asked for a name, use something recognisable such as “Kimpanion”. Copy the generated token before leaving the page; Kimai only shows it once. If API access is missing, ask your Kimai administrator. Kimai's illustrated token guide shows these steps.
  3. Open Kimpanion. On a fresh Mac installation, the window opens beneath the menu-bar icon. On later launches, click that icon to show it. On iPhone or iPad, open the app normally.
  4. Enter the Kimai server URL. Use the installation's base address, for example https://kimai.example.com. If Kimai is installed in a subdirectory, include it: https://example.com/kimai. Do not append /api, a language/login page such as /en/login, or a timesheet page. Use the final HTTPS address if your browser redirects you.
  5. Paste the token into API access token and choose Connect. Paste only the token, without “Bearer”, quotation marks or your Kimai password. A successful connection opens your timesheet. Check the server shown above the week view, or in the iPad sidebar, to confirm the connection.

Treat your API token like a password. Do not share it or its QR code in screenshots or support messages. Companion currently uses manual URL and token entry; it does not scan Kimai QR codes. Your Kimai password and Apple Account password do not belong in the API token field.

Record and review time

Use Timesheet, Reports and Settings at the bottom of the window. On a wide iPad layout, these are in the sidebar. Select a day in the week view to see its entries; use the arrows to change weeks.

Creating, editing and deleting entries and starting, stopping or restarting timers are free for your first saved account. Reports, timer merging and additional accounts require a subscription. A subscription does not change your permissions on the Kimai server.

Troubleshoot a connection

“Authentication failed. Check the API token.”

Make sure the token belongs to the account on the server you entered. Paste the token itself, not your web password or the word “Bearer”. If the token was revoked or you no longer have it, create a new one in Kimai. For a saved account, open Settings → Manage Accounts → your account, paste it into Replace API access token and choose Save connection.

The server cannot be reached, redirects, or returns HTTP 404

Open the same server in your browser on the same device. Check your internet connection and connect to your organisation's VPN if required. Confirm that you entered the base HTTPS URL, including any installation subdirectory, without a login page or /api. Companion requires a trusted HTTPS connection; ask your administrator to resolve certificate errors or API access restrictions. If the browser works but Companion does not, send support the exact error without your token.

I can connect, but projects, entries or team members are missing

Check the selected account and date range, then use Refresh on the timesheet or Refresh report in Reports. Customers, projects and activities must be available to your Kimai account. Team Time only includes entries permitted by the server, and the user filter lists people with entries in the selected period. If the same data is unavailable in Kimai's website, ask your administrator about permissions or assignments.

Saving fails, or the app says “Write outcome uncertain”

Check the dates, times and selected project/activity. Kimai may reject a change because of permissions, locked/exported entries or server rules. If the outcome is uncertain, refresh and check whether the entry was already saved before trying again, to avoid creating a duplicate. Include the exact error when contacting support.

Accounts, subscriptions and settings

What is included for free, and what needs a subscription?

Free access lets you connect one account, view its timesheet, create/edit/delete entries and start/stop/restart timers. A monthly or annual subscription unlocks My Time and Team Time reports, merging restarted timers, and additional accounts. Eligible new subscribers can receive a one-week free trial; the app shows Apple's current price and your trial eligibility before purchase. One subscription covers iPhone, iPad and Mac using the same Apple Account. After expiry, your first saved account retains free time entry and timer management. Additional saved accounts remain readable and their running timers can still be stopped. Reports and merging are unavailable until you subscribe again. Removing the first account makes the next saved account your free account.

How do I purchase, restore or cancel a subscription?

Open Settings → Subscription to choose a plan, Restore purchases or Manage subscription. Use the Apple Account that made the purchase. Apple handles payments and cancellation; you can also manage subscriptions with Apple. Removing a Kimai account or uninstalling Companion does not cancel a subscription. The subscription screen links to the Privacy Policy and Terms of Use.

How does the Mac window work?

The first launch opens the window pinned beneath the menu bar. Later launches start hidden; click the menu-bar stopwatch or elapsed time to show or hide it. Switching apps leaves the window open so you can return with Command-Tab. Closing the window hides it but leaves Companion running. Drag its title bar to detach it, then use Settings → App Settings → Pin below menu bar to restore its position. To exit completely, choose Quit Kimpanion.

Why has a timer not updated on another device?

Make sure both devices show the same Kimai account. Companion checks running timers about every five seconds while active and refreshes when you return to it. iPhone and iPad do not continuously refresh in the background. On Mac, monitoring continues while Companion is running, even with the window closed. Use Refresh to update the timesheet immediately. Closing or quitting Companion does not stop a timer on your Kimai server.

Can I use more than one Kimai account?

With a subscription, open Settings → Manage Accounts → Add account and enter the other server's URL and token. Use the account switcher, or open an account's settings and choose Use this account, to change the account displayed. Switching does not stop the other account's timers. Add connections separately on each device; Companion does not synchronise saved account setup between devices.

Can I work offline?

Companion needs a connection to your Kimai server to load and save entries. Offline editing and synchronisation are not currently supported.

What does “Merge restarted timers” do?

This optional subscriber feature combines time from a restarted timer with its original entry and is off by default. It requires an active subscription; without one, restarted timers remain separate entries. In Settings → Manage Accounts → your active account, enable Merge restarted timers. Your administrator must first provide a timesheet custom field of type Number (without decimal) with the exact Internal title related_timesheet_id, accessible to your account. The app checks for the field when you enable the setting.

For reliable merging, both Rounding of the start time in minutes and Rounding of the end time in minutes must be 0 in your Kimai instance settings. The merged entry does not preserve the break between sessions. Leave the setting off if you need separate entries for each session.

How do I change the time format or appearance?

Open Settings → App Settings to choose light, dark or system appearance and 12-hour or 24-hour time entry. Dates and times follow the timezone configured on your Kimai account.

How do I remove an account?

Open Settings → Manage Accounts → your account → Remove account. This removes the saved connection from this device. It does not delete the Kimai account or server timesheets, stop server timers or cancel a subscription. You can revoke the API token separately in Kimai. Contact your Kimai administrator to delete server-side records or the Kimai account itself.

Contact support

Email info@kimpanion.app for help with Kimpanion. For a missing Kimai login, API permission or project assignment, contact your Kimai administrator.

Include your app version and build number, device and operating-system version, the steps you took, what you expected, and the exact error. A screenshot can help if you hide client names and other private information. Never send API tokens, token QR codes, passwords or payment details.