This article will guide you through creating a user with access group assigned in BioStar 2 server via BioStar 2 API.
You can find a more detailed introduction to BioStar 2 New Local API in this article : [BioStar 2 API] How To Use BioStar 2 New Local API
In this article, you can learn how to call an API function to create users with access group to your BioStar 2 server. This article will explain how to create users and add them to access groups at the same time via one API call.
This article also includes a sample code of a C# program that incorporates the API, and also an example of API call made via Postman, a program used for building & testing RESTful API calls.
Part 1. API Call & Parameters
[POST]: /users
You can also find information regarding this API in the following link : Create New User API Documentation
[Body Parameters]
| Parameters | Type | Required | Description |
|---|---|---|---|
| users: | Y | ||
| user_id | String | Y | ID of the User. Unique. When User ID Type in Setting > Server is set to Number, a number between 1 and 4294967295 can be entered. When Alphanumeric is set, a combination of alphabetic characters and numbers can be entered. Do not use spaces when entering ID. Numbers or Alphanumeric characters can be set for user_id. For more details, refer to Setting Section of this documentation. |
| name | String | N | Name of the user. Up to 48 characters. |
| user_group_id:id | Number | Y | ID of the User Group that the user will be under. Refer to User Group Section of this documentation for listing available User Groups. |
| disabled | Boolean | N | Toggle User active or not; false for active, true for non-active. |
| start_datetime | Date/Time | Y | Start active period for the User. |
| expiry_datetime | Date/Time | Y | End active period for the User. |
| String | N | Email address of the User. | |
| department | String | N | Department of the User. Up to 64 characters. |
| user_title | String | N | Title of the User. |
| photo | Base64 | N | Photo of the User. |
| phone | String | N | Phone number of the User. |
| permission:id | Number | N | Operator Level of the User. None: The user has no operator privilege. To use this Operator Level, remove permission parameter from the API Request. Administrator: The user can use all menus. User Operator: The user can only use the USER and PREFERENCE menus. Monitoring Operator: The user can use the MONITORING and PREFERENCE menus and only view the DASHBOARD, USER, DEVICE, DOOR, ZONE and ACCESS CONTROL menus. Video Operator: The user can only use the VIDEO menu. T&A Operator: The user can only use the TIME ATTENDANCE menu and only view the USER menu. User: The user can only view own information and T&A records. |
| access_groups | Array | N | Add Access Group to user. Can enter more than 1 Access Group. |
| :id | Number | N | ID of the Access Group that the User will have access. Required if you want to add 'access_groups'. |
| :name | String | N | Name of Access group that the user will have access to. |
| login_id | String | N | Required when permission parameter is not removed. |
| password | String | N | Required when permission parameter is not removed. |
| user_ip | String | N | Limit the access of the User so he/she can only login from the registered IP Address. The user IP can be entered in the format xxx.xxx.xxx.xxx. Each octet can only be entered in numbers between 0 and 255. Users whose user IP is not registered can log in from any IP. |
| pin | Number | N | PIN of the user. Maximum 32 digit. |
| fingerprint_templates | N | Add fingerprint data to a user. | |
| :finger_mask | Boolean | N | Set to True to mark the fingerprint as a duress fingerprint. When threatened by someone to open the door, the user can authenticate using this fingerprint to send an alarm signal to BioStar 2. |
| :template0 | Raw | N | First scan template of the fingerprint. Required if you are adding 'fingerprint_templates' |
| :template1 | Raw | N | Second scan template of the fingerprint. Required if you are adding 'fingerprint_templates' |
| :isNew | Boolean | N | |
| cards:id | Number | N | Add card credential to user. |
| credentials:face | Array | N | Main container of face credential |
| :raw_image | Raw | N | Raw image of the face scan. Required if you are adding 'credentials:face' |
| :templates | Array | N | Container of face templates Required if you are adding 'credentials:face' |
| ::template | Raw | N | Face template of user |
| credentials:visualFaces | Array | N | Main container of Visual Face credential for user. |
| : template_ex_normalized_image | Base64 | N | Cropped image ready for visual face extraction. Required if you are adding 'credentials:visualFaces' |
| :templates | Array | N | Container of the templates Required if you are adding 'credentials:visualFaces' |
| ::credential_bin_type | Number | N | UNKNOWN = -1 FACE_TEMPLATE = 0 FACE_TEMPLATE_IMAGE = 1 FACE_RAW_IMAGE = 2 FACE_TEMPLATE_EX = 5 FACE_TEMPLATE_EX_IR = 6 FACE_TEMPLATE_EX_NORMALIZED = 7 FACE_TEMPLATE_EX_PICTURE = 8 Required if you are adding 'credentials:visualFaces' |
| ::templateEx | Raw | N | Visual Face template data which includes FaceStation F2 and the new BioStation 3. Required if you are adding 'credentials:visualFaces' and using BioStation 3 or FaceStation F2 |
| ::templateExIr | Raw | N | Visual Face IR template data, but only used in FaceStation F2 v1.x.x. The F2 v2.x.x and BioStation 3 does not use IR templates. Required if you are adding 'credentials:visualFaces' and using FaceStation F2 v1.x.x |
| :template_ex_picture | Base64 | N | Parameter for Upload Picture raw data Required if you are adding 'credentials:visualFaces' |
* Since we are trying to create a user with access group, we'll need to include "acess_groups" parameter.
Part 2. Request Body & Response Model
[Request Body Example]
{ "User": { "name": "AGTEST", "user_id": "99999", "user_group_id": { "id": 1, "name": "All Users" }, "disabled": "false", "start_datetime": "2001-01-01T00:00:00.00Z", "expiry_datetime": "2030-12-31T23:59:00.00Z", "access_groups": [{ "name": "TTTEST", "id": 15 } ], "login_id": "api2", "password": "Peter3820@" } } |
[Response Example: Fail]
{ "Response": { "code": "202", "link": "https://support.supremainc.com/en/support/home", "message": "User who has same id already exists" } } |
[Response Example: Successful]
{ "UserCollection": { "total": "1", "rows": [ { "user_id": "99999", "name": " AGTEST " } ] }, "Response": { "code": "0", "link": "https://support.supremainc.com/en/support/home", "message": "Success" } } |
Part 3. Console Create User with Access Group Example
This is a sample of Visual C# console application made for those who might need some guide for integrating the BioStar 2 New Local API.
You can simply copy & paste the source code to use the same function in your own integration.
[Create Users Method Source Code]
static async void CreateUserTask() { if (sessionID == null) { Console.WriteLine("You must log in first!"); return; } CookieContainer cookieContainer = new CookieContainer();
HttpClientHandler handler = new HttpClientHandler(); handler.CookieContainer = cookieContainer;
HttpClient httpClient = new HttpClient(handler);
HttpClient client = new HttpClient(handler); httpClient.DefaultRequestHeaders.Add("bs-session-id", sessionID); cookieContainer.Add(new Uri("https://127.0.0.1"), new Cookie("bs-session-id", sessionID));
string resourceAddress = "https://127.0.0.1/api/users";
JavaScriptSerializer serializer = new JavaScriptSerializer(); Console.WriteLine("Enter USER NAME: "); string UserName = Console.ReadLine(); Console.WriteLine("Enter USER ID: "); string UserID = Console.ReadLine(); Console.WriteLine("Enter USER LOGIN ID: "); string User_login_id = Console.ReadLine(); Console.WriteLine("Enter USER LOGIN PASSWORD: "); string User_login_pw = Console.ReadLine();
string payload2 = "{ \"User\": "; payload2 = payload2 + "{\"name\": \"" + UserName + "\", "; payload2 = payload2 + "\"user_id\": \"" + UserID + "\","; payload2 = payload2 + "\"user_group_id\": { \"id\": 1, \"name\": \"All Users\" },\"disabled\": \"false\",\"start_datetime\": \"2001-01-01T00:00:00.00Z\", \"expiry_datetime\": \"2030-12-31T23:59:00.00Z\", "; payload2 = payload2 + "\"access_groups\"": [{\"name\": \"TTTEST\",\"id\": 15 }],"; payload2 = payload2 + "\"login_id\": \""+ User_login_id +"\", "; payload2 = payload2 + "\"password\": \"" + User_login_pw + "\"}}"; Console.WriteLine(payload2); StringContent sc = new StringContent(payload2, Encoding.UTF8, "application/json");
HttpResponseMessage httpResponse = httpClient.PostAsync(resourceAddress, sc).Result;
if (httpResponse.IsSuccessStatusCode == true) { Console.WriteLine("User has been created"); string httpResponseBody = await httpResponse.Content.ReadAsStringAsync(); Console.WriteLine(httpResponseBody); } else { Console.WriteLine("User Creation Failed"); Console.WriteLine(httpResponse.ToString()); } } |
[After Creating User Successfully]
Part 4. Create User with Access Group via Postman
[Request Example: Headers]
*You must use the ‘be-session-id’ value from the response header of the Login API call to authenticate API use for other API calls.
[Request Example]
[Response Example: body]
