web sdk troubleshooting

Resolving common Web SDK errors

Verifying Web SDK connectivity

Complete these checks in order before investigating any specific error.

Confirm that the Web-based SDK role exists and is activated

Open Config Tool, go to System, then Roles. Look for the Web-based SDK role in the list.

If the role does not exist, create it. See the Web SDK Role Setup section for instructions.

If the role exists, confirm that it is activated. If the role is deactivated, right-click it and select Maintenance, then Activate.

Confirm the server assignment and network card binding

Click the Web-based SDK role, then click the Resources tab.

Verify these settings:

• The role is assigned to the correct server.
• The Network card is set to Any, unless you have a specific reason to bind it to a particular network interface.

If the network card is bound to a specific interface, the Web SDK only listens on that interface's IP address. This means localhost does not work if the loopback adapter is not on the selected interface. Leave it set to "Any" unless your network architecture requires otherwise.

Confirm the port and SSL settings

Click the Properties tab and note these values:

• Port (default: 4590)
• Streaming port (default: 4591)
• Base URI (default: WebSdk)
• Use SSL connection (on or off)

These values determine the URL format and whether you test with HTTP or HTTPS in the next check.

Test connectivity from the server

Open a command prompt on the server hosting the Web-based SDK role and send the appropriate request based on your SSL setting.

If SSL is OFF

curl -v http://localhost:4590/WebSdk/

If SSL is ON

curl -v -k https://localhost:4590/WebSdk/

A successful connectivity test shows a connection to the server and an HTTP response. Without authentication credentials, the server returns an HTTP 401 response. This is expected and confirms the Web SDK role is running and reachable.

In the response, look for:

< HTTP/1.1 401 Unauthorized

If the server returns any HTTP response code, the role is alive and the connectivity test has passed. Proceed to the next check.

If instead the connection times out, is refused, or is reset, the role is not reachable. Go back and verify the earlier checks.

Important

Testing from localhost eliminates firewall and network variables. If the role does not respond on localhost, the problem is with the role configuration itself, not the network.

Do not test in a browser. The Web SDK is a REST API, not a web page.

Do not test from a remote machine until the localhost test succeeds.

Do not test report queries, entity operations, or any other API endpoint before confirming the base URL /WebSdk/ responds.

Test the server hostname or IP from the server itself

Still on the same server, send the same request again but replace localhost with the server's actual hostname or IP address.

If SSL is OFF

curl -v http://YOUR-SERVER:4590/WebSdk/

If SSL is ON

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

If the localhost test succeeded but this check fails, the issue is the network card binding in the Resources tab. The role is running but is not listening on the expected network interface. Go back and verify the Network card setting.

This step also validates that the hostname resolves correctly on the server itself.

Test connectivity from the remote machine

Only after the localhost test and the hostname-or-IP test succeed, send the same request from the machine that will be connecting to the Web SDK.

If SSL is OFF

curl -v http://YOUR-SERVER:4590/WebSdk/

If SSL is ON

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

If this test fails while the localhost test and the hostname-or-IP test succeeded, the problem is a firewall, network rule, or DNS resolution issue between the two machines. This is not a Web SDK issue. Check the firewall rules, routing, and DNS configuration between the two machines.

Warning

Never share passwords, credentials, or Application IDs in plain text over email or in support tickets. If you need to share request output for diagnostic purposes, redact all credentials before sending.

Fixing connection refused errors

If you cannot connect to the Web SDK server, verify these points in order:

1. Verify the Web-based SDK role is running

   • Open Config Tool, go to System, then Roles
   • Confirm the Web-based SDK role is active and the server is reachable

2. Confirm the server address and port

   • The default port is 4590
   • Check both the server address and port configuration

3. Check firewall and network settings

   • Ensure ports 4590 and 4591 are open
   • Confirm no firewall or network rule is blocking access

4. Test DNS resolution

   • If using a domain name, confirm it resolves correctly
   • If needed, connect directly using the server's IP address

Fixing HTTP 404 Not Found errors

If the Web SDK returns HTTP 404, verify that your URL includes the base URI path. The default base URI is WebSdk.

Incorrect

http://server:4590/

Correct

http://server:4590/WebSdk/

If you changed the base URI in the Web SDK role properties, use the configured value instead of WebSdk.

Fixing SSL certificate trust errors

Use this section to diagnose and resolve certificate-trust errors during Web SDK development.

Symptoms

• 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
• Connection works on the server itself but fails from your application
• Connection works only when certificate verification is skipped

What is happening

The Web SDK is presenting the Security Center server's self-signed certificate. The machine making the request does not trust that certificate and refuses the connection. The server is working correctly. The fix is on the requesting side.

Confirm that the failure is a certificate trust issue

Send an HTTPS request from your machine without disabling certificate verification:

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

If the output contains SSL certificate problem, SEC_E_UNTRUSTED_ROOT, or certificate verify failed, the cause is confirmed.

If the request fails with a TLS handshake or protocol error instead, first verify that the Web-based SDK role is configured for HTTPS. Certificate trust guidance applies only after the TLS connection starts successfully.

Then send the same request with certificate verification disabled:

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

If this returns an HTTP response, the Web SDK is reachable and certificate trust is the only issue. Continue with the resolution options.

Choose a resolution

• Disable certificate verification for testing. Use this only on a private, isolated network.
• Install the certificate in the trusted store on each machine that connects to the Web SDK. Installing it on the server alone is not enough.
• Replace the self-signed certificate with a CA-signed certificate. Install a certificate issued by a trusted Certificate Authority on the Security Center server through Server Admin.

For more information, see Getting Started with Security Center Web SDK.

Fixing HTTP 401 Unauthorized errors

A 401 error means the server did not receive an acceptable Authorization header. This occurs when the header is missing or when the authentication scheme is not recognized.

Problem: Missing or unrecognized Authorization header

• Authorization header is not included in the request
• Authorization header does not start with "Basic "

If the header starts with Basic , use the response code to narrow the credential problem:

Header content	Response	What to check
Non-Base64 content after Basic	HTTP 500	Base64-encode the credential string.
Base64 content without the password separator (:)	HTTP 400	Use the username;applicationId:password format.
Base64 content with a password separator but no ; between username and Application ID	HTTP 403	Add the Application ID after the username and separate them with ;.
Well-formed credentials with an incorrect username, Application ID, password, SDK privilege, or certificate type	HTTP 403	Verify the account, SDK certificate, and Web SDK sign-in requirements.

Solution:

1. Include the Authorization header in every request

2. Ensure the header starts with "Basic " followed by the encoded credentials

3. Check the Authorization header format:

   Authorization: Basic BASE64-ENCODED-CREDENTIALS

Authentication format details

The Web SDK uses HTTP Basic Authentication with the Application ID included.

Example:

• Username: apiuser
• Application ID: KxsD11z743Hf5Gq9mv3+5ekxzemlCiUXkTFY5ba1NOGcLCmGstt2n0zYE9NsNimv
• Password: mypassword
• Combined: apiuser;KxsD11z743Hf5Gq9mv3+5ekxzemlCiUXkTFY5ba1NOGcLCmGstt2n0zYE9NsNimv:mypassword
• Base64 encode the combined string and use it in the Authorization header

Fixing HTTP 403 Forbidden errors

A 403 error means the Web SDK accepted the Basic authentication scheme but rejected the credential content or the account. Common causes include an incorrect username or password, a missing or wrong Application ID, an account that does not meet the Web SDK sign-in requirements, or a certificate type mismatch.

Reading the Web SDK log to identify the rejection reason

The 403 response body is empty. The Web SDK role writes the rejection reason to the Windows Event Viewer Genetec log on the server, where each entry appears at level Error from source GenetecWebSdk.exe. The entry's "Additional info" footer includes Logger name: Genetec.Sdk.Web.Authorization.WebSdkSession, which identifies Web SDK authentication failures.

To find the entry:

1. On the Web SDK server, open Event Viewer.
2. Navigate to Applications and Services Logs > Genetec.
3. Filter by Source: GenetecWebSdk.exe and Level: Error.
4. Locate the entry with a timestamp matching the failing request.

For the broader Event Viewer log-collection workflow that Technical Support uses, see "Viewing event and application logs" in the Genetec guide Working with logs and traces for Security Center.

A failed-logon entry has this format:

WebSdk logon failed on server <server> because: FailureCode: <code>, SessionId: <session>

Exception:
<exception message, or "No exception">

The FailureCode value names which check the Directory ran and rejected. Match the value to the corresponding row to find the fix.

FailureCode	Meaning	Action
InvalidCredential	The username does not exist on this Directory, or the password does not match.	See Verifying credentials.
InsufficientPrivileges	The account authenticated, but does not have the Log on using the SDK privilege.	See Checking user privileges.
CertificateRegistrationError	The Application ID was missing, malformed, did not match an SDK certificate registered on this Directory, or the certificate's connection limit was reached. The exception line names the specific cause, for example The client certificate's application id is invalid or corrupted, The client certificate could not be located on disk., The specified client certificate is not part of your Security Center license, or The specified client certificate registration exceeded the limit allowed by your Security Center license.	See Confirming the certificate type matches the system. For the "exceeded the limit" exception, the certificate's licensed concurrent-connection cap is reached; wait for an existing connection to time out, or have your administrator raise the cap.
UserAccountDisabledOrLocked	The account exists but is deactivated, or has been locked out.	Reactivate or unlock the account in Config Tool.
PasswordExpired	The account's password expired under the system password policy.	Sign in interactively as the account to set a new password, then retry.
MissingRequestUserChangePassordEvent	The account is flagged "must change password at next logon", but the Web SDK does not present an interactive password-change prompt.	Sign in interactively as the account to set a new password, or clear the flag in Config Tool.
BruteForceThrottling	The Directory throttled the account or its origin after repeated failures.	Wait for the throttle to clear, then retry with correct credentials.
DisallowedBySchedule	The account is restricted by a logon schedule that excludes the time of the request.	Update the account's logon schedule, or retry within the allowed window.
InsufficientSecurityLevel	The account's security level does not meet the threshold the Directory requires.	Adjust the account's security level.
LicenseError	The Web SDK could not allocate a license for this connection (no Web SDK license is active on the Directory, or the license does not cover this Web SDK role).	Verify the Web SDK license on the Directory.
Failed	A non-specific logon failure occurred. The Directory did not report a more precise reason.	Inspect the Web SDK and Directory logs for additional context, then retry.
Timeout	The logon attempt timed out before the Directory responded.	Verify Directory health and network reachability between the Web SDK role and the Directory, then retry.

Cases that produce no log line

Some responses are emitted by the Web SDK Basic authentication layer before the Directory is consulted, and produce no Event Viewer entry from Genetec.Sdk.Web.Authorization.WebSdkSession. The cases are:

• HTTP 401, when the Authorization header is missing or does not start with Basic.
• HTTP 400, when the decoded credential string has no : separator between the user portion and the password.
• HTTP 500, when the content after Basic is not valid Base64.
• HTTP 403, when the decoded credential string contains a password separator (:) but no ; between the username and the Application ID.
• HTTP 403, when repeated logon failures for the same username;applicationId pair trigger a local Web SDK throttle. While throttled, further attempts for that pair return 403 with no Event Viewer entry until the throttle clears.

The first four cases are covered in Fixing HTTP 401 Unauthorized errors, where the credential-format matrix maps each response code to a fix.

Verifying credentials

Problem: The credential content is wrong or the account type is unsupported.

Solution:

1. Verify the username and password are correct
2. Ensure the account is a Security Center local user (Active Directory users cannot authenticate)
3. Confirm the Application ID matches your SDK certificate
4. If you build the Authorization header yourself, confirm the decoded value uses the username;applicationId:password format

Web SDK sign-in requirements:

• Security Center local user account
• "Log on using the SDK" privilege
• Valid SDK certificate with matching Application ID
• Certificate type must match the system environment

Checking user privileges

Problem: The account does not have the Log on using the SDK privilege.

Solution:

1. Open Config Tool and edit the user account
2. Grant Log on using the SDK privilege
3. Save the changes
4. Restart the Web-based SDK role
5. Retry the request after the role is active

How to restart the Web-based SDK role

Important

Restarting the Web-based SDK role disconnects active Web SDK sessions and event streams. In production, coordinate the restart with any applications that depend on live Web SDK connections.

1. In Config Tool, go to System, then Roles
2. Right-click the Web-based SDK role
3. Select Maintenance, then Deactivate
4. Wait a few seconds
5. Right-click the role again
6. Select Maintenance, then Activate

Confirming the certificate type matches the system

Problem: The SDK certificate does not match the system environment.

• Development certificates work only with development systems
• Production certificates are required for demo and production systems

Solution: Verify that your certificate type matches your environment.

System Type	Required Certificate	Common Mistake
Development	Development certificate only	Using production certificate
Demo	Production certificate only	Using development certificate
Production	Production certificate only	Using development certificate

Development Application ID:

KxsD11z743Hf5Gq9mv3+5ekxzemlCiUXkTFY5ba1NOGcLCmGstt2n0zYE9NsNimv

This Application ID works only with development systems. If used on demo or production, you always get a 403 error.

To obtain a production certificate, request one through the Development Acceleration Program (DAP).