Table of Contents
-
Introduction
-
What is the Dolibarr REST API?
-
Setting Up API Access in Dolibarr
-
Authentication Methods and API Tokens
-
Overview of the User Endpoint
-
Creating a User via API
-
Reading User Data
-
Updating User Information
-
Deactivating or Deleting Users
-
Assigning Users to Groups and Permissions
-
Advanced User Properties and Metadata
-
Managing External Users with the API
-
Best Practices for User Account Automation
-
Handling API Errors and Responses
-
Integrating the API with Third-Party Systems
-
Securing API Access and Preventing Abuse
-
Using Webhooks for Real-Time User Updates
-
Logging and Monitoring API Activities
-
Limitations and Known Issues with User Management via API
-
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.