This article explains how to set up the import and synchronization of users and groups in SMARTFENSE by querying an external API. It details the connection setup, JSON key mapping, creation and update rules, and handling of capitalization and empty fields.
The configuration is available under Users and Groups > Import and Synchronization > From API.
Prerequisites
- An accessible external API that returns user data in JSON format.
- A valid authentication token for that API.
- Administrator access to the SMARTFENSE instance.
Connecting to the API
Fill out the following fields so SMARTFENSE can query the API:
- API URL: the address to which SMARTFENSE sends the request.
- Authentication Token: the corresponding access token.
Field Mapping
This section allows you to map SMARTFENSE fields to the keys in the JSON returned by your API.
Mapping Example
If the API returns the key user-id and you want to use it as the username, set the mapping between SMARTFENSE’s username field and the API’s user-id key.
Keys should be entered without quotes.
Required Fields
The following fields are mandatory:
- First Name
- Last Name
The rest of the fields are optional.
When a User Is Created or Edited
- If a user present in the API response does not exist in SMARTFENSE, they will be created.
- If the user already exists, they will be updated.
Identification is done by the username specified in the API response. If not specified, the platform uses the first part of the email (the part before the @).
It is not possible to edit the username or email address of an existing user through this functionality.
Use of Capitalization
Usernames
SMARTFENSE is case-insensitive when determining if a user exists. When creating a new user, the format returned by the API is preserved.
Groups
For groups, functional areas, and hierarchical levels, capitalization is case-sensitive. If the API returns names without an exact match, a second search ignoring case is attempted.
Other Relevant Cases
- Emails are always stored in lowercase.
- First and last names are formatted with an initial capital letter for each word.
- The UPN preserves the exact format returned by the API.
Behavior with Empty Fields
| Field | Behavior if Missing in Response |
|---|---|
| Language | New users take the language of the importing administrator. Existing users keep their current language. |
| Username | Generated from the first part of the email. |
| Without an email, the user cannot be imported. | |
| Status | New users are created as Active. Existing users keep their current status. |
| Role | New users are created as End User. Existing users keep their current role. |
| Phone, Employee ID, UPN | Remain empty. |
Online Help
Each field on the screen includes an (i) icon to its right. Hovering over the icon opens a popup window with specific help for that field.
💡 Best Practices
- Ensure the API always returns First Name, Last Name, and Email, as these are mandatory.
- Clearly define the JSON key mapping before enabling automatic synchronization.
- Maintain consistency in group names to avoid duplicates caused by case differences.
- Test the integration in a controlled environment before synchronizing users in production.
- Periodically rotate the authentication token and update it in SMARTFENSE to avoid service interruptions.