Skip to end of metadata
Go to start of metadata

In 2N® Access Commander, there is available HTTP REST API which gives the opportunity to completely control 2N® Access Commander, including read, modify, create or delete data from it.

API serves for integration purposes with any possible 3rd party systems in real-time, since no direct access to Access Commander's database is provided:

Before you start

Icon
  • HTTP REST API documentation including release changes can be found on the following link: https://wiki.2n.cz/acc/latest/en/6-http-api (it takes a while to fully load)
  • API endpoints are available on the address: https://ip_or_name_address/api/v2/
  • no additional license is required - HTTP REST API is available in every Access Commander installation
  • uses HTTPS protocol with TLS 1.2 for communication on default port 443
  • in default, uses self-signed certificate, SSL certificate verification needs to be disabled in order to start communication with API in this case
  • (optionally) CA signed certificate can be installed to 2N® Access Commander as described in the following article: SSL Certificate - How to add CA signed certificate to 2N® Access Commander web
    *If using CA signed certificate, Access Commander needs to be accessible on name address which matches name address in the certificate instead of an IP address.
  • Communication with API is secured by username and password authentication
  • The commands format supported is JSON only
  • Supported methods are GET, POST, PUT, DELETE
  • After initial authentication, every other command to API is authenticated by cookies which Access Commander send as a response to successful login

EXAMPLE 1: How to find out how to send a command to HTTP REST API

Let’s say we would like to login to Access Commander using an API in order to be able to use other commands.

We can easily see how it can be done on the web of 2N Access Commander itself because the web page of Access Commander is using the same HTTP REST API to access all data.

The following procedure will show how you can see which commands and parameters are used for each operation with data:

  •  load the Access Commander’s web ´page in your web browser and open the web browser's debug console by pressing F12 -> Network -> XHR (same for Chrome and Firefox browser).
    This will show a console in your web browser where we can see all the commands as you can see on the image below:



  • In order to see which command with which parameters is sent to API for login request, fill in login name and password in your web browser with enabled debugging console from previous step and press LOGIN button.

  • Access Commander will login in and in the web browser's debug console you can see multiple requests and one of them is the login request we are looking for:  




  • Select mentioned login request by clicking on it.
    In its Header you can see it uses PUT method
    In its Header you can see which endpoint it calls (/login)
    In its Request you can see which in which syntax data are sent.
    Using those data from web browser you can easily replicate this command in your application.


    After successful login, you will be also able to see in Response cookie required for commands which will follow

EXAMPLE 2: How to replicate sending command shown in example 1 from your application

To demonstrate this example we will use an application known as POSTMAN which is able to send HTTPS commands and read responses to its requests.

  • For the first time using the Access Commander after importing the appliance, it is needed to use the web interface to login as the administrator ("Admin") to change the default password ("2n")
  • While accessing the Access Commander using the REST API and using for example the app Postman, please, disable the SSL certificate verification first. There is no domain that can sign the certificate and a self-signed is not considered as trusted automatically by default.
  • Open the Postman and fill in the header as you saw in the previous example from your web browser debug console. Fill in also Body with request data you could see in the previous example. Don’t forget to set Method as PUT and Body as JSON.




  • Once you send the data to Access Commander API, when login is successful you will receive 200 OK a response along with other data and authentication cookies.

 

 

EXAMPLES:


In this section, we are ready to post the commands. First of all, we use the valid credentials to login:

(Let's consider we have an Access Commander using an IP 192.168.0.250, username: Admin, Password: Admin1234)

 

 

 

Login command:

Command:

PUT https://192.168.0.250/api/v2/login

Body(data to be sent):

{"login":"Admin","password":"Admin1234","longTimeLogin":true}

 

____________________________________________________________________________________________________________________________________________________

 

List of current users:

Now we want to receive a list of users with all the parameters

Command:

GET https://192.168.0.250/api/v2/users


Body(data to be sent):
{}

____________________________________________________________________________________________________________________________________________________

 

Getting information about a specific user.

Each user has a unique ID called UUID. It is possible to get from the previous command.

(Lets say our user has a UUID: e7207ded-b864-424b-ad0f-e06b9d8f7527)

Command:

GET https://192.168.0.250/api/v2/users/e7207ded-b864-424b-ad0f-e06b9d8f7527


____________________________________________________________________________________________________________________________________________________

 

Creating a new user:

Now we want to create a new user with the name UserAPI. This user will belong to the company with the ID=1

Command:

POST https://192.168.0.250/api/v2/users

 

Body(data to be sent):

{"Name":"UserAPI","Company":{"Id":1}}

 

In the answer, there will be a parameter E.G.: "ID": "09e7eab1-7b80-4071-89c9-4969a61354e1"

 

____________________________________________________________________________________________________________________________________________________

 

Adding a user to a group:
We need to know first the name of the group we want to add the user to.

Command:

Answer:
{
    "count"1,
    "data": [
        {
            "Name""Home",
            "Id""511720dc-ef0b-4e7c-b63a-4a54b350792d",
            "ModifiedGuid"0,
            "Company": {
                "Id"1,
                "Name""My Company"
            },
            "Users": [],
            "VisitorCards": []
        }
    ]
}

 

 

After that, we can use the answer for adding the user to the specific group:

Command:

PUT https://192.168.0.250//api/v2/users/4edab7c2-a6fc-45e8-af21-2542a21b26f7/groups


Body(data to be sent):

[{"Id":"511720dc-ef0b-4e7c-b63a-4a54b350792d"}]

____________________________________________________________________________________________________________________________________________________

 

Adding an RFID card for this new user:

If it is a new user and no one else could edit this user, we can assume the ModifiedGUID=0 , it is not needed to use this parameter then.

Command:

POST https://192.168.0.250/api/v2/users/09e7eab1-7b80-4071-89c9-4969a61354e1/cards

 

Body(data to be sent):

{"Identification":"12345678"}

 

____________________________________________________________________________________________________________________________________________________

 

Updating RFID card (similar for other parameters):

For maintaining database consistency, we need to use a specific ID for each parameter to prevent multiple processes from modifying data at the same time. This is called ModifiedGUID and we need to get this information from the parameter before we change it. Let's say another process changed the RFID card number 3 times already to the number 12342622. We are going to find out this now.

Command:

GET https://192.168.0.250/api/v2/users/09e7eab1-7b80-4071-89c9-4969a61354e1

 

Answer:

"Cards": [
            {
                "Identification""12342622",
                "Description""",
                "Id""25d79b1f-8612-4c44-859b-e04f89e19bb5",
                "ModifiedGuid"3
            }

 

Now we know the GUID=3 and we can change the card number to 12121212 (note: we are adding the ID of the card position to the URL):

Command:

PUT https://192.168.0.250/api/v2/users/09e7eab1-7b80-4071-89c9-4969a61354e1/cards/25d79b1f-8612-4c44-859b-e04f89e19bb5


Body(data to be sent):
{"Identification":"12121212","ModifiedGuid":3}

____________________________________________________________________________________________________________________________________________________

 

Creating 2 codes for a user (1234, 9876) (Note: Ordinal = ID of a code):

Command:

POST https://192.168.0.250/api/v2/users/09e7eab1-7b80-4071-89c9-4969a61354e1/codes


Body(data to be sent):
{"SwitchCode":"1234","User":{"Id":"e7207ded-b864-424b-ad0f-e06b9d8f7527"},"Ordinal":0}

Command:

Body(data to be sent):
{"SwitchCode":"9876","User":{"Id":"e7207ded-b864-424b-ad0f-e06b9d8f7527"},"Ordinal":1}

____________________________________________________________________________________________________________________________________________________

Deleting the 2nd code:
We need to know the code ID the ModifiedGuid first:
Command:

Answer:
 
 "Codes": [
            {
                "Ordinal"0,
                "SwitchCode""1234",
                "Id"4,
                "ModifiedGuid"0,
                "Collisions": []
            },
            {
                "Ordinal"1,
                "SwitchCode""9876",
                "Id"5,
                "ModifiedGuid"0,
                "Collisions": []
            }
        ],


To the URL we need to put the ID of the code we want to delete.

Command:
 
Body(data to be sent):
{"Identification":"9876","ModifiedGuid":0}   

 

 

  • No labels