The Security Center Web SDK is an HTTP-based API that allows applications to interact with Security Center over HTTP. It provides an interface for managing entities, monitoring events, and executing operations within your Security Center system.

The Web SDK is a specialized Security Center role that acts as an HTTP API gateway. It allows HTTP clients to interact with Security Center using standard HTTP requests.

Key capabilities:

• Entity management: Create, read, update, and delete Security Center entities (cardholders, credentials, visitors, access rules, etc.)
• Real-time events: Subscribe to and receive live event streams
• Report execution: Query and filter historical events
• Alarm operations: Trigger and acknowledge alarms
• Custom operations: Execute actions and macros

Understanding how the Web SDK works will help you build robust integrations.

flowchart LR
    subgraph App[Your Application]
        A1[HTTP API calls]
        A2[JSON/XML responses]
    end

    subgraph WebSDK[Web SDK Role]
        W1[Session Management]
        W2[Query Processing]
    end

    subgraph SC[Security Center Directory]
        S1[Entity Storage]
        S2[Event System]
    end

    App -->|HTTP/HTTPS| WebSDK --> SC

How it works:

1. Your application makes HTTP requests to the Web SDK Role
2. Web SDK Role authenticates your requests and creates a session
3. Session maintains a connection to Security Center and caches data for performance
4. Security Center processes operations and returns results through the Web SDK

When you make your first authenticated request, the Web SDK creates a session for you. This session:

• Maintains your connection to Security Center
• Tracks subscriptions to real-time events
• Persists your context like creation partition settings

How sessions are identified:

Sessions are tied to the unique combination of (credentials + Application ID + Web SDK instance).

Shared session example:

Client A: user1 + appID1 → http://server:4590/WebSdk/
Client B: user1 + appID1 → http://server:4590/WebSdk/

Result: Both clients share one session

Implications of shared sessions:

• Settings configured by Client A (like /creationpartition) affect Client B
• Event subscriptions from Client A are shared with Client B
• Session timeout is reset by activity from either client
• Both clients see the same session state

Separate sessions (load balancing):

When connecting to different Web SDK instances, sessions are completely independent:

Client A: user1 + appID1 → http://server1:4590/WebSdk/  (Session 1)
Client B: user1 + appID1 → http://server2:4590/WebSdk/  (Session 2)

Result: Two separate sessions

Session lifecycle:

The Web SDK uses HTTP Basic Authentication with a specific credential format that includes your SDK certificate.

Every request must include an Authorization header with the following format:

Authorization: Basic [Base64-encoded credentials]

The credentials before Base64 encoding must follow this format:

username;applicationId:password

Where:

• username = Security Center user's username
• applicationId = Your SDK certificate's Application ID
• password = Security Center user's password

User account:

• Must be a local Security Center user (Active Directory users cannot log on to the Web SDK)
• Must have the "Log on using the SDK" privilege enabled

SDK certificate:

• Required for all Web SDK connections
• Must be included in your Security Center license
• Application ID must match your environment type:
  • Development systems: Use development certificate
  • Demo/Production systems: Use production certificate (request via DAP program)

Certificate mismatch: Using a development certificate on a production system (or vice versa) will always result in HTTP 403 Forbidden errors.

1. Obtain your credentials:

• Username: apiuser
• Password: mypassword
• Application ID: KxsD11z743Hf5Gq9mv3+5ekxzemlCiUXkTFY5ba1NOGcLCmGstt2n0zYE9NsNimv

2. Combine into credential string:

apiuser;KxsD11z743Hf5Gq9mv3+5ekxzemlCiUXkTFY5ba1NOGcLCmGstt2n0zYE9NsNimv:mypassword

3. Base64 encode the string:

YXBpdXNlcjtLeHNEMTF6NzQzSGY1R3E5bXYzKzVla3h6ZW1sQ2lVWGtURlk1YmExTk9HY0xDbUdzdHQybjB6WUU5TnNOaW12Om15cGFzc3dvcmQ=

4. Include in HTTP header:

Authorization: Basic YXBpdXNlcjtLeHNEMTF6NzQzSGY1R3E5bXYzKzVla3h6ZW1sQ2lVWGtURlk1YmExTk9HY0xDbUdzdHQybjB6WUU5TnNOaW12Om15cGFzc3dvcmQ=

Using curl:

curl -X GET "https://server:4590/WebSdk/" \
  -H "Authorization: Basic YXBpdXNlcjtLeHNEMTF6NzQzSGY1R3E5bXYzKzVla3h6ZW1sQ2lVWGtURlk1YmExTk9HY0xDbUdzdHQybjB6WUU5TnNOaW12Om15cGFzc3dvcmQ=" \
  -H "Accept: text/json"

curl -X POST "https://server:4590/WebSdk/action?q=UnlockDoor({door-guid})" \
  -H "Authorization: Basic ..." \
  -H "Accept: text/json" \
  -H "Content-Length: 0"

Credential protection:

• Basic Authentication only Base64-encodes credentials (not encrypted)
• Always use HTTPS in production to protect credentials in transit

Session security:

• Sessions are tied to (credentials + Application ID + Web SDK instance) combination
• Multiple client applications using the same credentials connecting to the same Web SDK instance will share the same session
• Shared sessions mean shared state and shared settings (like /creationpartition)
• Use separate user accounts or different Application IDs when session isolation is needed on the same instance

Let's walk through making your first Web SDK request to verify your setup.

The simplest API call tests if the Web SDK role is online:

curl -X GET "https://your-server:4590/WebSdk/" \
  -H "Authorization: Basic [your-encoded-credentials]" \
  -H "Accept: text/json"

Expected response (HTTP 200):

{
  "Rsp": {
    "Status": "Ok"
  }
}

Common errors:

• Connection refused: Web SDK role is not running, or the firewall is blocking port 4590
• HTTP 401: Missing Authorization header or unsupported authentication scheme
• HTTP 403: Invalid credentials, user lacks "Log on using the SDK" privilege, or certificate type mismatch

Having connection or authentication issues? See the Troubleshooting Guide for detailed solutions.

Let's retrieve information about a specific cardholder:

curl -X GET "https://your-server:4590/WebSdk/entity?q=entity={cardholder-guid},Name,FirstName,LastName,EmailAddress" \
  -H "Authorization: Basic [your-encoded-credentials]" \
  -H "Accept: text/json"

Response:

{
  "Rsp": {
    "Status": "Ok",
    "Result": {
      "Name": "John Doe",
      "FirstName": "John",
      "LastName": "Doe",
      "EmailAddress": "[email protected]"
    }
  }
}

What this demonstrates:

• Field projection (requesting specific fields)
• Entity querying by GUID
• Session creation (first request creates your session)
• Response format

Search for all active cardholders whose first name contains "John":

curl -X GET "https://your-server:4590/WebSdk/report/CardholderConfiguration?q=FirstName=John,FirstNameSearchMode=Contains,AccessStatus@Active,Page=1,PageSize=10" \
  -H "Authorization: Basic [your-encoded-credentials]" \
  -H "Accept: text/json"

Response:

{
  "Rsp": {
    "Status": "Ok",
    "Result": [
      {"Guid": "12345678-1234-1234-1234-123456789abc"},
      {"Guid": "87654321-4321-4321-4321-cba987654321"}
    ]
  }
}

What this demonstrates:

• Report endpoint usage
• Filtering and search modes
• Pagination
• Returns GUIDs (use with /entity endpoint to get full details)

All Web SDK responses follow a consistent structure.

{
  "Rsp": {
    "Status": "Ok|Partial|Fail|TooManyResults",
    "Result": { /* response data or error details */ }
  }
}

Status values:

Failure response example:

{
  "Rsp": {
    "Status": "Fail",
    "Result": {
      "SdkErrorCode": "UnableToRetrieveEntity",
      "Message": "Could not get the entity, does it exists? Guid: 00000000-0000-0000-0000-000000000099"
    }
  }
}

The Web SDK supports both JSON and XML responses. Control the format using the Accept header:

Recommendation: Always use Accept: text/json for best performance.

The Web SDK uses HTTP status codes primarily for transport-level errors. Business logic errors return HTTP 200 with failure details in the response body.

Before using the Web SDK, you need to create an instance of the Web-based SDK role. The Web SDK role is the web API server.

1. From the Config Tool home page, open the System task and click the Roles view.

2. Click Add an entity and select Web-based SDK.

3. In the "Creating a role: Web-based SDK" dialog, specify the role information:

   1. Select the Server that will host the role.
   2. Click Next.
   3. Enter the Entity name.
   4. Enter the Entity description.
   5. If you use partitions, select a Partition for the role. Partitions are logical groupings used to control the visibility of entities. Only users of the specified partition can view or modify the role.
   6. Click Next.
   7. On the Creation summary page, review the information and then click Create or Back to make changes. The following message is displayed after creating the Web-based SDK role: The operation was successful.
   8. Click Close.

You configure the settings of the Web-based SDK role from the Roles view of the System task in Security Center Config Tool.

Click the Properties tab to configure the web API server settings.

• Port: This port is used for API requests. The default value is 4590.
• Streaming port: This port is used to stream real-time events. The default value is 4591.
• Base URI: The base URL used for API requests. The default value is WebSdk.
• Use SSL connection: When enabled, the web service address uses HTTPS instead of HTTP. Although the label mentions SSL, the Web-based SDK role only supports TLS 1.2 and newer.

The Web SDK uses the same TLS certificate as the Security Center server hosting the role. By default, Security Center installs with a self-signed certificate.

TLS version requirements:

• Minimum version: TLS 1.2
• Not supported: TLS 1.0, TLS 1.1

Clients must support TLS 1.2 or newer to connect to the Web SDK over HTTPS.

Self-signed certificate behavior

Because the default certificate is self-signed, no public Certificate Authority has verified it. Every HTTP client, whether it is a mobile app, a Python script, a Java application, or a .NET service, refuses to connect to a server presenting an untrusted certificate. The connection fails before any data is exchanged.

This is expected behavior. It is not a problem with Security Center. It requires a deliberate configuration step on your side before you can connect.

Option 1: Disable certificate verification in your HTTP client

Every HTTP client has a setting to skip certificate verification. Use this only on a private, isolated network.

curl:

curl -k https://YOUR-SERVER:4590/WebSdk/

Python:

requests.get("https://YOUR-SERVER:4590/WebSdk/", verify=False)

C# (.NET):

var handler = new HttpClientHandler();
handler.ServerCertificateCustomValidationCallback = (message, cert, chain, errors) => true;
var client = new HttpClient(handler);

Java:

SSLContext sslContext = SSLContext.getInstance("TLS");
sslContext.init(null, new TrustManager[]{new X509TrustManager() {
    public void checkClientTrusted(X509Certificate[] chain, String authType) {}
    public void checkServerTrusted(X509Certificate[] chain, String authType) {}
    public X509Certificate[] getAcceptedIssuers() { return new X509Certificate[0]; }
}}, new SecureRandom());
HttpClient client = HttpClient.newBuilder().sslContext(sslContext).build();

Node.js:

const https = require("https");
const agent = new https.Agent({ rejectUnauthorized: false });
fetch("https://YOUR-SERVER:4590/WebSdk/", { agent });

Option 2: Install the Security Center certificate in your client's trusted store

Export the certificate from the Security Center server and install it in the trusted certificate store on every machine that connects to the Web SDK. Once installed, your HTTP client treats the certificate as trusted and connects without errors.

Installing the certificate on the Security Center server does not make client machines trust it. It must be installed on each connecting device, or distributed through a device management tool.

Option 3: Replace the default certificate with a CA-signed certificate

Replace the default self-signed certificate on the Security Center server with one issued by a trusted Certificate Authority. The TLS certificate is configured through Server Admin on the machine hosting the Security Center server. Once replaced, clients connect without any additional configuration.

Common certificate error messages

If your client throws one of these errors, the cause is the untrusted certificate. The fix is on your side, not on the server.

• SSL certificate problem: self-signed certificate
• SEC_E_UNTRUSTED_ROOT (0x80090325) - The certificate chain was issued by an authority that is not trusted.
• The remote certificate is invalid according to the validation procedure
• NET::ERR_CERT_AUTHORITY_INVALID
• Your connection is not private

The configuration values determine the URL that applications use to connect to the Web SDK:

https://{server}:{port}/{base-uri}/

• {server} is the hostname or IP address of the server hosting the Web SDK role.
• {port} is the API port (default 4590).
• {base-uri} is the base URI (default WebSdk).

For example:

• Without TLS: http://{server}:4590/WebSdk/

• With TLS enabled: https://{server}:4590/WebSdk/

Security recommendation: Always use HTTPS (TLS) in production environments to protect authentication credentials and sensitive data.

Click the Resources tab to configure the servers assigned to this role.

• Servers: Defines which servers host the Web-based SDK role. You can assign one or more servers to provide failover capability.

Your Security Center license specifies the number of concurrent SDK connections allowed. Understanding how connections are counted is critical for license compliance and capacity planning.

How connections are counted:

Each unique combination of (credentials + Application ID + Web SDK instance) counts as one concurrent connection against your license.

Example scenarios:

1. Multiple clients, same credentials, same Web SDK instance:

   Client A: user1 + appID1 → http://server:4590/WebSdk/
   Client B: user1 + appID1 → http://server:4590/WebSdk/
   
   Total = 1 connection (shared session)
   

   Both clients share the same session.

2. Single client, load balancing across 3 Web SDK instances:

   user1 + appID1 → http://server1:4590/WebSdk/ = 1 connection
   user1 + appID1 → http://server2:4590/WebSdk/ = 1 connection
   user1 + appID1 → http://server3:4590/WebSdk/ = 1 connection
   
   Total = 3 connections (separate sessions)
   

   Even though you're using the same credentials, each Web SDK instance has its own session.

3. Different users on the same instance:

   user1 + appID1 → http://server:4590/WebSdk/ = 1 connection
   user2 + appID1 → http://server:4590/WebSdk/ = 1 connection
   
   Total = 2 connections (separate sessions)
   

4. Different Application IDs on the same instance:

   user1 + appID1 → http://server:4590/WebSdk/ = 1 connection
   user1 + appID2 → http://server:4590/WebSdk/ = 1 connection
   
   Total = 2 connections (separate sessions)
   

Session and connection comparison:

License capacity planning:

If your license allows 5 concurrent SDK connections, you can have up to 5 different (user + Application ID + Web SDK instance) combinations connected simultaneously.

Load balancing impact:

When implementing load balancing with multiple Web SDK instances:

• Each instance connected with the same credentials consumes one license connection
• If you load balance across 3 instances with the same user + Application ID, you consume 3 connections
• Plan your license capacity accordingly when deploying multiple Web SDK instances

Connection limit exceeded:

When the license connection limit is reached, new connection attempts will fail with HTTP 403 Forbidden.

Example:

• License allows 5 concurrent connections
• 5 connections are currently active
• A 6th connection attempt returns HTTP 403

Security Center supports role failover and multiple Web SDK instances for high availability and scalability. However, it is critical to understand that your client application is responsible for managing connections in both scenarios.

How failover works:

Role failover is a backup operating mode managed by the Security Center Directory. When you assign multiple servers to a Web SDK role:

1. Primary server - The role normally runs on this server
2. Secondary servers - Standby servers that can take over if the primary fails
3. Automatic switchover - When the primary server goes down (failure or maintenance), the Directory automatically transfers the role to the next available secondary server in the failover list

Implementation requirements:

Your client application must implement:

• Connection retry logic to detect when the primary server is unavailable
• Discovery mechanism to identify which server is currently hosting the active role
• Automatic reconnection to the new active server
• Session re-establishment (re-authentication, re-subscribe to events, etc.)

Multiple Web SDK role instances:

For scalability, you can create multiple independent Web-based SDK roles in the same Security Center system:

• Same server with different ports:

  • Role 1: http://server:4590/WebSdk/
  • Role 2: http://server:4591/WebSdk/
  • Role 3: http://server:4592/WebSdk/

• Different expansion servers:

  • Role 1: http://server1:4590/WebSdk/
  • Role 2: http://server2:4590/WebSdk/
  • Role 3: http://server3:4590/WebSdk/

• Combination of both:

  • Role 1: http://server1:4590/WebSdk/
  • Role 2: http://server1:4591/WebSdk/
  • Role 3: http://server2:4590/WebSdk/

Key takeaway: Security Center provides the infrastructure (failover mechanism, multiple role support), but your client application is responsible for all connection management and request distribution logic.

The Web SDK does not implement rate limiting. Your request throughput is limited only by:

• Network bandwidth
• Web SDK server resources (CPU, memory)
• Security Center Directory capacity

We provide a comprehensive Postman collection with example requests for all Web SDK endpoints:

Documentation: https://documenter.getpostman.com/view/26277955/2s9YeK5VtN

The collection includes:

• Pre-configured authentication
• Examples for all endpoint categories
• Request templates you can customize
• Collection variables for easy configuration

Recommended tools:

• Postman - Full-featured API client with collection support
• curl - Command-line testing and scripting

Now that you understand the basics, explore these topics:

• Entity Operations - CRUD operations, batch updates, multi-value fields
• Events and Alarms - Real-time event streaming and alarm monitoring
• Referencing Entities - Entity discovery, search capabilities, and parameter formats
• Performance Guide - Optimization strategies and caching
• Troubleshooting - Common issues and solutions

The Security Center Web SDK provides multiple endpoint categories for different operations. This reference shows all available endpoints organized by functional area.