Citrix License Activation Service

Overview

This document describes how to complete License Server registration with Citrix Cloud using the Key Registration Service (KRS) Trust API. Registration binds a specific License Server instance to your Citrix Cloud customer account so that licensing attestation and reporting can proceed.

The onboarding consists of three customer-facing steps:

Under the hood, when the License Server generates the code in Step 1 it contacts the KRS token endpoint (POST https://trust.citrixnetworkapi.net/root/trust/v1/token) on your behalf. You do not call the token endpoint directly. The License Server does. After a code is issued, the License Server polls Citrix Cloud in the background and transitions to REGISTERED automatically once the registration is approved or confirmed.

Authentication model: As a customer you do not use a Citrix Cloud service key anywhere in this workflow. Step 1 runs against the local License Server. The verify and confirm calls (Steps 2 and 3) are not authenticated with a service key — see each step and the Prerequisites for details.

Prerequisites

Before you begin, ensure the following:

• License Server reachability (local API): Network access from the machine running the script to the License Server over HTTPS on TCP port 8083 (the License Server’s local API port). Any intervening firewall must allow this.
• License Server health: The License Server service is running and healthy.
• Outbound connectivity to Citrix Cloud: The License Server must have working outbound HTTPS connectivity to the Citrix Cloud trust endpoints. Generating the code requires the License Server to contact Citrix Cloud. If outbound connectivity or the proxy is broken, the code request can return HTTP 200 but with no code (inspect the status/result values).
• TLS trust: The License Server trusts the Citrix Cloud certificate chain (up-to-date root CAs), and no SSL-inspecting proxy should be replacing the Cloud certificate.
• PowerShell: Available to run the provided script.
• License Server admin credentials: The script accepts an administrator user name and password for the License Server.
• KRS API access (Steps 2 & 3): Ability to reach the KRS Trust API verify and confirm endpoints below. A Citrix Cloud service key is not required for these calls.
  • https://trust.citrixnetworkapi.net/root/trust/v1/verify/<CustomerId>
  • https://trust.citrixnetworkapi.net/root/trust/v1/confirm/<CustomerId>
• TODO: From KRS API spec — the authentication method for these calls (note: this is not a service key).

Note:

The sample script disables TLS certificate validation for convenience in controlled/test environments. In production, trust the License Server’s certificate rather than disabling validation.

Step 1 - Obtain a Registration Code on the License Server

Purpose

Ask the local License Server to generate a Citrix Cloud registration code. This short, opaque code is later used to verify and confirm the registration. No interactive console login is required for the API path.

How to run the script

Run the provided PowerShell script with three mandatory parameters:

• AdminUsername - License Server administrator user name.
• AdminPassword - Password for that account.
• LicServer - host name or IP address of the License Server.

# Obtain a Citrix Cloud registration code from the License Server
# Replace <...> with your values and the script name with the one provided to you.
.\Get-LicRegisterCode.ps1 `
    -AdminUsername <admin> `
    -AdminPassword <password> `
    -LicServer   <license-server-host>
<!--NeedCopy-->

What the request looks like (for automation)

If you are building your own automation instead of using the script, the recommended, replicable path is the following request. Send it directly to the License Server local API.

POST https://<LicServer>:8083/sls_unauth/services/sls
Content-Type: application/soap+xml; charset=utf-8

<soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope"><soapenv:Body><WSLCCRegisterRequest><locale>en-US</locale></WSLCCRegisterRequest></soapenv:Body></soapenv:Envelope>
<!--NeedCopy-->

Notes

• Transport: HTTPS (TLS) on TCP port 8083. Replace <LicServer> with the License Server host name or IP.
• The charset=utf-8 portion of the Content-Type header is required.
• locale is the message locale (for example, en-US).

What a successful run returns

The License Server responds with HTTP 200 and a SOAP envelope containing a WSLCCRegistrationStatusResponse. Read these fields:

The script prints and returns the code, and also saves it to a text file on the machine (for example, registercode.txt under a ProgramData subfolder).

Important:

Do not treat HTTP 200 as success on its own. Always inspect registrationStatus and retCode. A registration code exists only when registrationStatus = PENDING. Treat the code as an opaque string. Do not assume a fixed length.

Possible outcomes of Step 1

After a code is issued, the License Server begins polling Citrix Cloud in the background at the interval Cloud specifies and completes automatically once the registration is approved. The code is valid only until its expiry. If it expires before verification or confirmation completes, restart Step 1 to obtain a fresh code.

Step 2 - Verify the Registration (KRS Trust API)

Call the KRS Trust API to verify the registration using the code obtained in Step 1.

No service key required. These calls are not authenticated with a Citrix Cloud service key.

Endpoint

POST https://trust.citrixnetworkapi.net/root/trust/v1/verify/<CustomerId>
<!--NeedCopy-->

Replace <CustomerId> with your Citrix Cloud customer ID.

Request headers

Request body

TODO: from KRS API spec — exact JSON request body for the verified call (including how the Step 1 registration code and any identifiers are supplied).

Response body

TODO: from KRS API spec — exact JSON response body for the verified call.

Error codes

TODO: from KRS API spec — HTTP status codes and error payloads returned by the verified endpoint, with meaning and recommended action.

Step 3 - Confirm the Registration (KRS Trust API)

Call the KRS Trust API to confirm (complete) the registration.

No service key required. These calls are not authenticated with a Citrix Cloud service key.

Endpoint

POST https://trust.citrixnetworkapi.net/root/trust/v1/confirm/<CustomerId>
<!--NeedCopy-->

Replace <CustomerId> with your Citrix Cloud customer ID.

Request headers

Request body

TODO: from KRS API spec — exact JSON request body for the confirmed call.

Response body

TODO: from KRS API spec — exact JSON response body for the confirmed call.

Error codes

TODO: from KRS API spec — HTTP status codes and error payloads returned by the confirmed endpoint, with meaning and recommended action.

Once verification and confirmation succeed, the License Server background polling detects the approval and transitions the instance to REGISTERED. The registration is then complete.

End-to-End Sequence Summary

1. Request a code (Step 1). Run the script (or POST the local API request) against the License Server. The License Server contacts Citrix Cloud, obtains a short registration code plus a verification URL and validity window, and reports registrationStatus = PENDING. Save the code.
2. Verify (Step 2). Call POST .../root/trust/v1/verify/<CustomerId> with the details from the KRS API spec.
3. Confirm (Step 3). Call POST .../root/trust/v1/confirm/<CustomerId> with the details from the KRS API spec.
4. Automatic completion. While the code is PENDING, the License Server polls Citrix Cloud at the Cloud-specified interval. When the registration is approved or confirmed, the License Server transitions to REGISTERED on its own and records the customer details. No further customer action is required.

If the code expires before Steps 2/3 complete, repeat Step 1 to obtain a fresh code and try again promptly.

Response & Error Codes Reference

The values below apply to the parts of the flow driven by the License Server (Step 1 and the automatic background completion). Codes for the KRS verify/confirm endpoints are supplied separately (see the TODO placeholders in Steps 2 and 3).

Registration status values

Registration result codes

Step 1 local-API HTTP outcomes

Troubleshooting

• HTTP 200 but no registration code: Re-check registrationStatus and retCode. This is usually an outbound connectivity, proxy, or certificate problem between the License Server and Citrix Cloud. Verify outbound HTTPS reachability, proxy settings, and TLS trust, then retry Step 1.
• Cannot reach the License Server on port 8083: Confirm the License Server service is running and that firewalls permit HTTPS to TCP 8083 from the machine running the script.
• HTTP 404 from Step 1: Ensure the request uses POST, the exact URL, the Content-Type: application/soap+xml; charset=utf-8 header (including charset=utf-8), and the exact SOAP body.
• Certificate / TLS failures (ERROR_WSL_CC_ENDPOINT_CERTIFICATE): Update root CAs on the License Server and ensure that no SSL-inspecting proxy is intercepting traffic to Citrix Cloud.
• Proxy failures (ERROR_WSL_PROXY_UNRESPONSIVE): Verify proxy address/port/credentials and that the proxy permits HTTPS to the Citrix Cloud endpoints.
• Code expired (ERROR_WSL_CC_ACTIVATION_CODE_EXPIRED): Restart Step 1 for a fresh code and complete Steps 2 and 3 promptly.
• Duplicate instance (ERROR_WSL_CC_INSTANCE_NOT_UNIQUE): Fully deregister the stale instance in Citrix Cloud (or contact Citrix Support to remove the duplicate), then retry.
• Registration seems stuck at PENDING: Confirm Steps 2 and 3 completed successfully and that the License Server remains to run with outbound connectivity so its background polling can complete. If the code has expired, restart Step 1.
• State reports UNKNOWN: Retry the status query. If it persists, check Cloud connectivity and the License Server logs, then re-attempt registration.
• Errors from Step 2 or Step 3 (KRS API): TODO: from KRS API spec — add KRS verify/confirm error handling guidance once the spec is supplied.

When contacting Citrix Support, include the License Server logs and, where available, the transaction identifier associated with the failed request.