Session and Profile Management

This guide explains how to connect HtkDoli to your Dolibarr ERP, and how to manage your different sessions (profiles) securely.

In HtkDoli, each connection to a Dolibarr instance is saved as a session (also called a profile). You can create as many sessions as you need — one per company, per instance or per user — and switch between them from the "Sessions space" home screen.

Connecting to your Dolibarr instance

Connecting to Dolibarr is done exclusively with an API key. HtkDoli does not ask for a password: there is no login-and-password sign-in.

To create a session, three pieces of information are mandatory:

Profile name: the name displayed in the session list and on the dashboard (for example: My Association).
Dolibarr URL: the full address of your instance (for example: https://mydoli.example.com).
API key: the key generated in Dolibarr for your user.

Where to find your API key? In Dolibarr: Avatar → Card → API key.

Optional fields

Username: your Dolibarr login. This field is purely informational; it is not used to authenticate (authentication relies solely on the API key).
Pappers API key: enables company search and auto-completion when creating third parties.
Entity number: for multi-entity Dolibarr installations (Multicompany module). The default value is 1.
Notes: a free space for your personal remarks.

Customizing the session

To spot your sessions at a glance, you can choose a color and a role icon (enterprise, accountant, technician, management, sales, HR, etc.) for each profile.

Creating a session — interface

When you open the app, the "Sessions space" screen appears with the list of your existing sessions.
Tap the + button (or "Create a session" if the list is empty).
Fill in at least the Profile name, the Dolibarr URL and the API key.
(Optional) Fill in the optional fields, choose a color and an icon.
Tap Save.

Until the three mandatory fields are filled in, the Save button stays inactive and the missing fields are highlighted.

Testing the connection and permissions

From a session's editing screen, two tools help you validate your configuration:

Test connection: checks that the URL and API key can reach your Dolibarr. ⚠️ If your instance uses http:// (insecure) instead of https://, the app warns you explicitly.
Check permissions: analyzes, module by module, the rights of your Dolibarr user to identify what will be accessible (or not) in the app.

Multi-Session and Profile Management

HtkDoli is designed for users managing several companies or working with several Dolibarr instances.

User interface

Session list: the "Sessions space" screen displays all your sessions as cards. You can search them (by name or URL) and sort them (by name or by last connection date).
Open / switch session: tap a session card to connect to it. To return to the list and switch to another session, leave the current session.
Add a session: tap the + button to create a new session.
Edit a session: tap a card's edit action to open the editor (name, URL, key, color, icon, etc.).
Delete a session: you can delete a session you no longer need. ⚠️ This deletion is permanent: it erases the profile, its API key and all its local data.

Purging or deleting a session

From an existing session's editor, two distinct actions are available:

Purge this session: deletes all local data (third parties, invoices, orders, etc.) but keeps the profile and the API key. A new synchronization will be required at the next opening. Useful to start from a clean cache without reconfiguring everything.
Delete this session: permanently deletes the profile, its API key (from the keychain) and all of its local data.

Strict data isolation

Security and privacy are at the heart of HtkDoli's architecture:

Protected API key: the API key is never stored in plain text in the database; it is kept in the device's secure Keychain, accessible only when the device is unlocked.
Separate databases: each profile has its own local SQLite database (Profile_{UUID}.store), protected by the system's file encryption.
No information leakage: the network cache, sessions, cookies and preferences (UserDefaults, App Group) are strictly tied to the active profile and cleared when you leave the session.
Clean session shutdown: when switching profiles or signing out, background processes (synchronization, Live Activities, scheduled notifications, widget data) tied to the previous profile are explicitly stopped and purged from memory to prevent any interference.

PIN code lock

A session can be protected by a 4-digit PIN code. When the lock is active, this code is required to access the session, adding an extra layer of protection in case of unauthorized access to the device.

Opening a session and initial synchronization

When you tap a profile to connect:

Preparation (~1 second, sometimes longer if the profile has never been opened on this device): an "Opening session…" overlay is displayed while the app loads your API key and prepares the local database.
Initial synchronization: the app starts retrieving your data from your Dolibarr (third parties, invoices, orders, etc.). You see the progress per module.
Entering the session: as soon as the sync has started, an "Enter (sync in background)" button appears at the bottom of the screen. Tap it to go straight to the dashboard without waiting for the end — the sync keeps running on its own in the background. Once synchronization is complete, the button becomes "Enter the session" (or "Enter (Offline Mode)" if there is no network).

During background sync

Once on the dashboard, a small "Synchronizing…" bubble floats at the top of the screen as long as the sync is not finished. Your lists (Third Parties, Invoices, etc.) fill up as downloads come in — you can browse them right away, they will enrich themselves automatically.

When the sync finishes:

The bubble disappears
A toast is shown: "Data up to date" (success), "Finished — offline mode" (no network, you will work on the local data), or "Finished with errors" (if there is a problem).

To wait for the sync or not?

It is up to you:

You wait (leave the sync screen open) if you want to see the detail of each module being synchronized (logs, progress) — useful for diagnostics.
You enter early if you know what you want to consult and do not need the detail. The UX comfort is better.

In all cases, the downloaded data is the same — only the UI while you wait changes.

Required Dolibarr permissions

For the connection and synchronization to work correctly, certain permissions and settings must be active on the Dolibarr side.

1. Enabling the REST API

Your Dolibarr instance must have the API/REST Web services module enabled.

Configuration: Log in to Dolibarr via a web browser, go to Setup > Modules/Applications and enable the "REST API" module.

2. User rights

The user whose API key you use must have the appropriate permissions in Dolibarr to interact with the modules.

API access: The user must be allowed to view and use the APIs.
Per-module rights: If you do not have the right to view "Third Parties" or "Invoices" in Dolibarr's web configuration, the API will deny access, and that data will not appear in HtkDoli.
Create/Modify: Create, edit or delete actions through the app also require the corresponding rights for your user in Dolibarr.

Screenshots

4 screenshots — click to enlarge