web sdk getting started

Getting Started with Security Center Web SDK

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.

What is the Web SDK?

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

Architecture Overview

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

Connection Flow

[Your Application] → HTTP/HTTPS → [Web SDK Role] → [Security Center Directory]
       ↓                              ↓                        ↓
  HTTP API calls              Session Management          Entity Storage
  JSON/XML responses          Query Processing            Event System

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

Important

Your application connects only to the Web SDK Role, not directly to the Security Center Directory server. The Web SDK handles all communication with Security Center on your behalf.

Sessions Explained

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 (username + Application ID + Web SDK instance).

Important

Multiple client applications using the same username and Application ID connecting to the same Web SDK instance will share the same session.

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:

Event	Behavior
First request	Session created, connection established to Security Center
Subsequent requests	Session reused, cached data returned when available
5 minutes of inactivity	Session expires and is cleaned up
Any request	Resets the 5-minute inactivity timer
Event subscription with open stream	Automatic keep-alive every 1 minute (session never expires)

Important

Settings like /creationpartition are session-specific. After 5 minutes of inactivity the session ends and these settings are cleared. Always call /creationpartition before operations if your session may have expired.

Authentication

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

Authentication Format

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

Requirements

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.

Step-by-Step Authentication

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=

Example Authentication Requests

Using curl:

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

Security Considerations

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 (username + 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

Your First API Call

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

Step 1: Test Connectivity

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 or malformed Authorization header
• 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.

Step 2: Query an Entity

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

Step 3: Search for Entities

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)

Response Format

All Web SDK responses follow a consistent structure.

Standard Response Structure

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

Status values:

Status	Description
Ok	Request completed successfully
Partial	Request partially succeeded (e.g., in a federated system, one server did not respond)
Fail	Request failed. Check the Error object for details
TooManyResults	Query exceeded the result limit. For entity configuration queries, use pagination to retrieve remaining results. For activity reports, refine your search criteria (narrower time range, more specific filters) or increase MaximumResultCount

Important

The Web SDK returns HTTP 200 for most requests, including failures. Always check Rsp.Status in the response body to determine the actual result of your request. Do not rely solely on the HTTP status code.

Failure response example:

{
  "Rsp": {
    "Status": "Fail",
    "Error": {
      "Message": "Unable to retrieve the entity",
      "SdkErrorCode": "UnableToRetrieveEntity"
    }
  }
}

Content Types

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

Accept Header	Format	Performance	Recommendation
text/json	JSON	Fastest	✅ Use this
application/json	JSON	Slower	For legacy compatibility (SC 5.7 and earlier)
text/xml	XML	Slower	When XML required
application/xml	XML	Slower	For legacy compatibility
*/*	XML	Slower	Default (not recommended)

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

HTTP Status Codes

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.

Status Code	When Returned
200 OK	All successful requests and most business logic failures. Check Rsp.Status for actual result
206 Partial Content	Partial results returned (used with streaming)
401 Unauthorized	Missing or malformed Authorization header
403 Forbidden	Invalid credentials, user lacks required privileges, certificate type mismatch, or license connection limit exceeded
414 URI Too Long	Query string exceeds maximum URL length
500 Internal Server Error	Catastrophic server error (check Web SDK role logs)

Important

The Web SDK intentionally returns HTTP 200 for most operations, even failures. This design ensures clients always receive a parseable response body with error details. Always check Rsp.Status in the response body to determine success or failure.

Web SDK Role Setup

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.

Procedure

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.

Configuration tabs

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

Properties tab

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.

TLS certificate

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 implications:

When connecting to a Web SDK instance using HTTPS with the default self-signed certificate, clients will encounter certificate validation errors because the certificate is not trusted by a Certificate Authority.

Common error messages:

• "Your connection is not private"
• NET::ERR_CERT_AUTHORITY_INVALID
• SSL certificate problem: self-signed certificate
• The remote certificate is invalid according to the validation procedure

Handling certificate errors:

Environment	Recommended Approach
Development	Bypass certificate validation in your client code, or trust the certificate locally
Production	Install a CA-signed certificate on the Security Center server

Warning

Bypassing certificate validation on public networks is a security risk as it exposes your application to man-in-the-middle attacks. On isolated private networks, self-signed certificates may be acceptable.

Endpoint format

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

https://<server>:<port>/<baseURI>/

• <server> is the hostname or IP address of the server hosting the Web-based SDK role.
• <port> is the API port (default 4590).
• <baseURI> 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.

Resources tab

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.

SDK Connection Licensing

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 (username + Application ID + Web SDK instance) counts as one concurrent connection against your license.

Important

The same user + Application ID connecting to different Web SDK instances counts as multiple connections.

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:

Scenario	Sessions	Connections
2 clients, same credentials, same instance	1 shared	1
2 clients, same credentials, different instances	2 separate	2
2 clients, different users, same instance	2 separate	2
2 clients, different Application IDs, same instance	2 separate	2

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

High Availability and Load Balancing

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.

Failover

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

Important

Security Center does NOT automatically redirect your API requests to the failover server. When failover occurs:

• The Directory switches the role to a secondary server
• Your client application must detect the connection failure
• Your client application must reconnect to the new active server
• There is no automatic request redirection

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.)

Load Balancing

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/

Important

Security Center does NOT automatically distribute or load balance requests across multiple Web SDK roles. Each role is completely independent. Your client application must:

• Decide which Web SDK role instance to connect to
• Distribute requests across multiple instances (if desired)
• Implement your own load balancing strategy (round-robin, least-connections, etc.)
• Manage separate sessions for each role instance

Summary

Feature	What Security Center Does	What Your Client Must Do
Failover	Directory automatically switches role to secondary server when primary fails	Detect connection failure, discover new active server, reconnect, and re-authenticate
Load Balancing	Nothing - each Web SDK role is independent	Choose which role instance to connect to, distribute requests, implement load balancing strategy

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.

Rate Limiting

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

Tools and Resources

Postman Collection

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

Testing Tools

Recommended tools:

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

Next Steps

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

Web SDK Endpoint Reference

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

Entity Endpoints

Endpoint	Method	Purpose
/entity/exists/{id}	GET	Check if entity exists
/entity/{id}	GET	Get complete entity data
/entity/basic/{id}	GET	Get basic entity properties only
/entity?q={query}	GET/POST	Read, create, update and execute actions
/entity/{id}	DELETE	Delete entity

Events Endpoints

Endpoint	Method	Purpose
/events	GET	Open event streaming connection
/events/subscribe?q={query}	GET	Subscribe to events
/events/subscribed	GET	List current subscriptions
/events/unsubscribe?q={query}	GET	Unsubscribe from events
/events/closeconnection/{connectionId}	POST	Close streaming connection
/events/RaiseEvent/{eventType}/{entityId}	POST	Raise system event
/events/RaiseCustomEvent/{customEventId}/{entityId}/{message}	POST	Raise custom event
/events/alarmMonitoring/{onOrOff}	POST	Toggle alarm monitoring

Alarm Endpoints

Endpoint	Method	Purpose
/alarm?q={query}	GET	Trigger alarms, acknowledge, check status
/activealarms	GET	Get list of active alarms

Report Endpoints

Endpoint	Method	Purpose
/report/{reportType}?q={query}	GET	Execute reports with filters

Task Operations

Endpoint	Method	Purpose
/tasks/public	GET	Get public saved tasks
/tasks/private	GET	Get private saved tasks
/tasks/execute/{guid}	POST	Execute saved task by GUID
/tasks/public/execute/{taskType}/{taskName}	POST	Execute public saved task
/tasks/private/execute/{taskType}/{taskName}	POST	Execute private saved task

Action Endpoints

Endpoint	Method	Purpose
/action?q={query}	POST	Execute action manager operations

Macro Endpoints

Endpoint	Method	Purpose
/activemacros	GET	Get running macros list
/activemacrosdetails	GET	Get detailed running macros info

Incident Endpoints

Endpoint	Method	Purpose
/incident?q={query}	PUT	Create incidents
/incident?q={query}	GET	Read incidents
/incident/{incidentGuid}	GET	Get specific incident

Custom Field Endpoints

Endpoint	Method	Purpose
/customField/{entityId}/{customFieldName}	GET	Get custom field value
/customField/{entityId}/{customFieldName}/{value}	PUT	Set custom field value
/customField/{entityType}/{customFieldName}/{dataType}/{defaultValue}	POST	Create custom field
/customField/{entityType}/{customFieldName}/Encrypt/{dataType}/{defaultValue}	POST	Create encrypted custom field
/customField/{entityType}/{customFieldName}	DELETE	Delete custom field

Configuration Operations

Endpoint	Method	Purpose
/	GET	Test service online status
/GetWebTokenEncoded	GET	Get encoded web token
/GetWebTokenDecoded	GET	Get decoded web token
/creationpartition/{partitionIds}	POST	Set default creation partitions
/ignoreremoteexception/{state}	POST	Configure exception handling

CustomEntityType Endpoints

Endpoint	Method	Purpose
/customEntityType/all	GET	Get all custom entity types
/customEntityType/{customEntityTypeDescriptorId}	GET	Get specific custom entity type
/customEntityType/{customEntityTypeDescriptorId}	DELETE	Delete custom entity type

Custom Card Format Endpoints

Endpoint	Method	Purpose
/customCardFormats/all	GET	Get all custom card formats
/customCardFormats/getByName/{name}	GET	Get card format by name
/customCardFormats/getByFormatId/{formatId}	GET	Get card format by format ID
/customCardFormats/getById/{id}	GET	Get card format by ID
/customCardFormats/add	POST	Create new custom card format
/customCardFormats/updateByName/{name}	PUT	Update card format by name
/customCardFormats/updateByFormatId/{formatId}	PUT	Update card format by format ID
/customCardFormats/updateById/{id}	PUT	Update card format by ID
/customCardFormats/deleteByName/{name}	DELETE	Delete card format by name
/customCardFormats/deleteByFormatId/{formatId}	DELETE	Delete card format by format ID
/customCardFormats/deleteById/{id}	DELETE	Delete card format by ID
/customCardFormats/exportByName/{name}	POST	Export card format XML by name
/customCardFormats/exportByFormatId/{formatId}	POST	Export card format XML by format ID
/customCardFormats/exportById/{id}	POST	Export card format XML by ID

License Usage Endpoints

Endpoint	Method	Purpose
/licenseItemUsage	GET	Get license usage information
/licenseItemUsage/{name}	GET	Get specific license item usage