When you start to set up and configure the platform, one of the first things you will have to set up and manage is the creation of companies and users, that can be made via API. This guide provides information, step-by-step instructions, and tips for configuring and managing company’s user states through our API, using the correct endpoints.
What is company’s user management?
It is the systematic process of controlling, organizing, and overseeing the activities related to user accounts within a company. The goal of user management is to ensure that authorized users have appropriate access to resources while maintaining the security and integrity of the system. Managing user states is crucial for maintaining security, compliance, and usability within backoffice, as it helps administrators control access and enforce policies effectively.
What is user states?
User states refer to the various conditions or statuses that users can occupy. These states typically represent different phases or modes of interaction with the backoffice, each with its own set of permissions, privileges, and functionalities. Managing user states is crucial for maintaining security, compliance, and usability within backoffice, as it helps administrators control access and enforce policies effectively.
To better manage user states, it is mandatory to understand that a user can only exist associated with a company. That is why we speak about company’s user, because the only way a user can be created is if it belongs to a certain company. In that context, the creation of a first user comes with the creation of the company during the onboarding process.
There are 4 different types of user states: created, valid, enabled and deactivated.
Created
The creation of a first user within a company is made by onboarding process.
This is the Onboarding API endpoint a new first user should use
For example,
{
"company": {
"externalId": "COMPANY-123",
"tradeName": "Shopery",
"legalName": "Shopery Networks SL",
"registrationNumber": "75120534G",
"shortDescription": {
"en_GB": "B2B e-commerce",
"es_MX": "Comercio electrónico B2B",
"es_ES": "Comercio electrónico B2B"
},
"longDescription": {
"en_GB": "Some long description of B2B e-commerce",
"es_MX": "Una descripción larga de comercio electrónico B2B",
"es_ES": "Una descripción larga de comercio electrónico B2B"
},
"additionalInformation": {
"en_GB": "Digital sales and procurement solutions",
"es_MX": "Soluciones en ventas digitales y procurement",
"es_ES": "Soluciones en ventas digitales y procurement"
},
"addresses": {
"name": "My direction",
"firstLine": "Edificio Palau del Mar",
"secondLine": "nº 1",
"city": "Barcelona",
"region": "Barcelona",
"postalCode": "08039",
"country": "ES"
},
"contact": {
"phone": "+34123456789",
"email": "contact@example.com"
},
"logoId": "img_01FPVZTMZY7ET28VB5C296DSMT",
"backgroundImageId": "img_01FPW04Q4886FH2AKJSMF4TR13",
"website": "http://example.com",
"customFields": [
{
"reference": "foundation-year",
"value": "2005"
}
]
},
"user": {
"externalId": "jhn_d",
"firstName": "John",
"lastName": "Doe",
"emailAddress": "john.doe@example.com",
"username": "john",
"password": "pass1234",
"activateLinkUrl": "http://example.com"
}
}
```
By default, when you create a new company, it is “enabled”, and the user has been created. This means that the user has been added to the system, but their email address is not yet confirmed as valid. Users who linger in the created state for 730 days and don’t validate their email address should pass to anonymization (more information about this in the “deactivated” section).
To pass to the next state, it is necessary to validate the email address, following the instructions sent by email.
To create new users within a created company:
- The Owner user should use this Market API endpoint
- The Company Admin user should use this Company API endpoint
For example,
{
"firstName": "John",
"lastName": "Doe",
"emailAddress": "john.doe@example.com",
"username": "john",
"roleIds": [
"rol_01FG8W4T7J621V8ZJNYRTM449M"
],
"passwordResetUrl": "https://example.com/reset-password"
}If a user wants to update or edit information of a user that already exits within a company, should use :
- If it is an Owner user this Market API endpoint
- If it is a Company Admin user Company API endpoint
For example,
{
"externalId": "jhn_d",
"firstName": "John",
"lastName": "Doe",
"emailAddress": "john.doe@example.com",
"language": "en_GB",
"roleIds": [
"rol_01FG8W5MNQNR47PBF8FJGX69J7"
],
"segmentId": "seg_01FSVYA3CC5BY7DT24TW2EXHJX",
"companyId": "com_01H4NEDA3WBPE00Z9NTKVG3FC0"
}Enabled
An “enabled” user state implies that data, information, settings, preferences, and features are turned on and operational.
After the validation process is correctly done, criteria are met for the user to become active, and the user is in enabled status, which means the user is actively managed and preserved.
In this state, users can perform any actions attributed to them by their final roles assigned, such as editing info, adding new users, deactivating users, changing roles or user permissions, among many others.
If a user needs to search for users and get their info, should use:
- If its an Owner user this Market API endpoint
- If it is a Company Admin role Company API endpoint
For example,
{
"id": "usr_01FGBJJT54JQRE74088MZ07X89",
"externalId": "jhn_d",
"readableId": 105768,
"firstName": "John",
"lastName": "Doe",
"emailAddress": "john.doe@example.com",
"roles": [
"rol_01FGBJKMMRARJC3C67Q5JB2Z25"
],
"segmentId": "seg_01FSVY8G4Y2NXAGTFXZFXYWKHE"
}Deactivated
This user state implies that the management and preservation of a user's state are turned off or disabled.
To deactivate a user in the backoffice the user must go to Companies —> Associated user —> Click the user —> Deactivate count (at the bottom of the page).
Only roles, such as owner or company admin with permission to deactivate users can deactivated them. This is done directly in the backoffice.
- The Owner user should use this API endpoint
- The Company Admin should use this API endpoint
A user with this kind of permission enabled can also deactivate its own user, in this case, it can be done directly in the backoffice.
- The Owner user should use this API endpoint
- The Company Admin should use this API endpoint
❗ There are some special cases to take into consideration:
👉 If an “owner” or “company admin” role with a wide range of permissions needs to be deactivated, first this user will have to give his roles and permissions to another user in the company, so there is a user able to manage and configure this kind of permissions. After doing this, this kind of user is able to deactivate themselves.
👉 A company cannot be without users; as a minimum, there has to be one user created, so if there is a last user that wants to be deactivated, the user should deactivate the company instead. It is not permitted to deactivate the last user of a company.
When a user is deactivated there is a 30-day grace period where users cannot login and are informed of deactivated status.
During this grace period, there is a possibility that the user is revoked, which means that the user passes from a deactivates state to an enabled state, and all the information, roles and permissions of the user are reestablished.
- The Owner user should use this API endpoint
- The Company Admin user should use this API endpoint
In line with General Data Protection Regulation (GDPR) requirements, any personally identifiable information must be anonymized if a user or associate company is deactivated. After the 30-day grace period the deactivated user account is anonymized, therefore no longer recognized as an existing user and all the information or reference to the person is irreversible removal and there is no possibility to recover this information.
A person also has the “right to be forgotten”, so a user can solicit this on an individual level and the user can be deactivated first and anonymized after 30 days.
Also, users who are inactive for 700 days will be deactivated and after 30 days will pass to anonymization, ensuring irreversible removal.
⛔ There is also the possibility to delete users under special conditions (an error importing company’s user for example).
This must be used with extreme care and warning because once the user is deleted it is irreversible.To cautiously delete users Owner user can use this API endpointTo cautiously delete users Company Admin user can use this API endpoint
