Table of Contents

  1. Introduction

  2. What is the Dolibarr REST API?

  3. Setting Up API Access in Dolibarr

  4. Authentication Methods and API Tokens

  5. Overview of the User Endpoint

  6. Creating a User via API

  7. Reading User Data

  8. Updating User Information

  9. Deactivating or Deleting Users

  10. Assigning Users to Groups and Permissions

  11. Advanced User Properties and Metadata

  12. Managing External Users with the API

  13. Best Practices for User Account Automation

  14. Handling API Errors and Responses

  15. Integrating the API with Third-Party Systems

  16. Securing API Access and Preventing Abuse

  17. Using Webhooks for Real-Time User Updates

  18. Logging and Monitoring API Activities

  19. Limitations and Known Issues with User Management via API

  20. Summary and Recommendations


1. Introduction

As ERP systems evolve toward cloud-native, connected architectures, APIs play a critical role in integrating data and automating operations. Dolibarr ERP & CRM includes a robust REST API that allows external systems to interface with nearly every aspect of the platform. One of the most important areas of interaction is user account management.

This guide explores how to manage user accounts programmatically using the Dolibarr REST API. From creating and updating users to assigning permissions and securing API access, we'll cover everything needed for effective integration.

2. What is the Dolibarr REST API?

The REST API is an interface provided by Dolibarr to allow external systems to perform CRUD (Create, Read, Update, Delete) operations. It follows RESTful principles, making it easy to integrate with various technologies and tools.

Available endpoints cover most modules, including:

  • Third parties (companies, contacts)

  • Products and services

  • Invoices and orders

  • Projects and tasks

  • Users and permissions

3. Setting Up API Access in Dolibarr

To use the REST API, you need to:

  • Enable the API module in Dolibarr (Home > Setup > Modules)

  • Create an API key/token from a user account

  • Set appropriate permissions for that user

  • Access the API via the endpoint: https://yourdomain.com/api/index.php

Dolibarr includes API documentation accessible via Swagger interface, usually at /api/index.php/explorer.

4. Authentication Methods and API Tokens

Authentication is performed using HTTP headers. The standard method uses an API token:

GET /users
Host: yourdomain.com
DOLAPIKEY: abcdef1234567890abcdef1234567890

Make sure to:

  • Never expose API keys in frontend code

  • Regenerate keys periodically for security

  • Use HTTPS to encrypt traffic

5. Overview of the User Endpoint

The base endpoint for user management is:

GET /users

Supported operations include:

  • GET /users: list all users

  • GET /users/{id}: retrieve a specific user

  • POST /users: create a new user

  • PUT /users/{id}: update an existing user

  • DELETE /users/{id}: delete a user

Each user object includes fields like:

  • login

  • firstname

  • lastname

  • email

  • admin

  • statut

6. Creating a User via API

To create a user:

POST /users
Content-Type: application/json
DOLAPIKEY: your_api_key

{
  "login": "jdoe",
  "password": "secret",
  "firstname": "John",
  "lastname": "Doe",
  "email": "jdoe@example.com",
  "admin": 0,
  "statut": 1
}

Dolibarr will return the new user’s ID if successful. Passwords must be strong and managed securely.

7. Reading User Data

To fetch a user’s data:

GET /users/123
DOLAPIKEY: your_api_key

This will return the JSON object for user ID 123, including personal data, login, status, and group memberships.

8. Updating User Information

To change a user's information:

PUT /users/123
Content-Type: application/json
DOLAPIKEY: your_api_key

{
  "email": "newemail@example.com",
  "lastname": "Doe-Smith"
}

Only include fields that need to be updated. Omitting others will leave them unchanged.

9. Deactivating or Deleting Users

To deactivate (rather than delete) a user:

PUT /users/123
{
  "statut": 0
}

To delete a user permanently:

DELETE /users/123

Use caution with deletions, as they may affect records linked to the user.

10. Assigning Users to Groups and Permissions

Group management is not directly handled through the /users endpoint. You need to:

  • Use /groups and /groups/{id}/users

  • POST to assign a user to a group

  • Configure group permissions in the UI or via API if supported

Permissions are inherited from group membership.

11. Advanced User Properties and Metadata

Advanced options include:

  • Custom fields (extrafields)

  • Language preference (default_lang)

  • Timezone (timezone)

  • External user flag (fk_soc for third-party association)

These properties improve user-specific configuration.

12. Managing External Users with the API

External users are those associated with clients or suppliers. When creating them:

  • Include the fk_soc field to link to a third party

  • Limit their module access appropriately

External users often have limited visibility, and their permissions should be tightly controlled.

13. Best Practices for User Account Automation

  • Validate all inputs before sending to API

  • Implement password strength rules

  • Automatically deactivate users no longer needed

  • Sync with external systems on a schedule

  • Document API usage and authorization scopes

14. Handling API Errors and Responses

Dolibarr returns standard HTTP status codes:

  • 200 OK: successful operation

  • 400 Bad Request: invalid data

  • 401 Unauthorized: invalid token

  • 404 Not Found: user not found

Always check responses and handle failures gracefully.

15. Integrating the API with Third-Party Systems

Typical integrations include:

  • HR systems (to create users upon onboarding)

  • CRMs or ticketing systems

  • External SaaS platforms that need Dolibarr user sync

Use webhooks, batch scripts, or middleware to sync data securely.

16. Securing API Access and Preventing Abuse

  • Rate-limit API calls

  • Monitor usage and logs

  • Use different tokens per application

  • Keep keys secret

  • Audit all external integrations

17. Using Webhooks for Real-Time User Updates

While Dolibarr does not include native webhooks, you can:

  • Extend modules to emit hooks

  • Use scheduled scripts to poll changes

  • Implement custom triggers to notify systems

These can help external systems stay in sync.

18. Logging and Monitoring API Activities

Dolibarr logs API activity in:

  • Apache logs (access and error)

  • Application-level logs if debug mode is enabled

  • External log aggregation tools via middleware

Log key events like user creation, password changes, and login attempts.

19. Limitations and Known Issues with User Management via API

  • Some user settings require manual UI configuration

  • No built-in audit trail for API changes

  • Extrafield handling can vary depending on configuration

Community contributions and patches may resolve some of these gaps.

20. Summary and Recommendations

Managing user accounts with the Dolibarr REST API offers flexibility and automation potential. By leveraging standard endpoints and best practices, businesses can streamline user provisioning, updates, and deactivations.

Administrators should ensure that API access is secure, error-tolerant, and integrated thoughtfully into existing workflows. As Dolibarr continues to evolve, the API remains a vital tool for scaling and modernizing ERP usage across diverse systems and teams.