XML Activation Service
The XML Activation Service Web service provides several activation-related web methods.
Refer to the SOLO Server New Activation Features white paper for more information on these new web services.
For SOLO Server Shared URL, this can be reached at https://secure.softwarekey.com/solo/webservices/XmlActivationService.asmx
- When using SOLO Server Shared / Custom URL, replace secure with your custom subdomain.
- When using SOLO Server Dedicated URL, replace secure.softwarekey.com with your domain.
- When using SOLO Server Self-Hosted, replace secure.softwarekey.com/solo in the URL with the path to your SOLO Server instance.
Please contact us if you need assistance determining the correct URL.
All web methods in this service use XML for both input and output (though the input parameter is defined as a string to allow POST access to the web service, the string must be in XML format). This allows new input and output values to be added without breaking backwards compatibility with existing implementations using the service.
If your integration with the web service validates the XML returned by the web methods, be sure to account for the possibility of new elements being returned in the result. This can easily be done by applying an XSLT transform to the result XML to filter out any new fields and then validating the transformed XML.
Each web method in this web service is documented by a series of documentation files named after the web method as follows:
- MethodNameInput.xml - Uncommented xml file with input xml structure.
- MethodNameInputDetails.xml - Commented xml file with input xml structure and comments on each input element.
- MethodNameInput.xsd - XSD schema file defining the input xml structure.
- MethodNameOutput.xml - Uncommented xml file with output xml structure.
- MethodNameOutputDetails.xml - Commented xml file with output xml structure and comments on each output element.
- MethodNameOutput.xsd - XSD schema file defining the input xml structure.
The SoftwareKey System offers an assortment of libraries which provide APIs that simplify the invocation of these web services from your application. This collection of API libraries includes:
- The Protection PLUS 5 SDK libraries, including the PLUSManaged library (for .NET applications), and the PLUSNative library (for native applications).
- The Automation Client library, which is included with Protection PLUS 4 SDK for native/unmanaged applications.
- The SwkClientServices2005 library, which is included with Protection PLUS 4 SDK for .NET/managed applications.
Please refer to the applicable product manuals and sample projects for more information on each library/API.
Please note that all date values returned by the above Web methods are in UTC time, using the ISO 8601 format as follows:
- YYYY-MM-DDTHH:MM.SSZ
ActivateInstallation
This web method is used to perform an activation for an installation on a given license. It returns activation codes and other license information related to activation.
Input
The values of these elements are as follows:
Parameter | Data Type | Required/Optional | Description |
---|---|---|---|
EncryptionKeyID | string | Required |
The Encryption Key ID used for encrypting, decrypting, digitally signing, and verifying requests and responses. This is included in the Encryption Envelope, which may be retrieved by clicking the Configure/Products menu and clicking Actions/View Encryption Key Data. |
LicenseID | int | Required for LicenseID/Password authentication, otherwise optional. | The License ID of the license which is being activated. |
Password | string | Required for LicenseID/Password authentication, otherwise optional. | For LicenseID/Password authentication, the customer password or license activation password. If provided for SerialNumber/ProductID validation, the customer password, license activation password, or for Assigned from List serials, the serial number password. |
SerialNumber | string | Required for SerialNumber/ProductID authentication, otherwise optional. | The Serial Number associated with the license which is being activated. |
ProductID | int | Required with SerialNumber/ProductID authentication, otherwise optional. | The Product ID with which the license was created. When present, the license's Product ID will be validated against the value in this element. Multiple ProductID elements can be included, in which case the license's Product ID will be validated to ensure it matches at least one of the values listed in the elements provided. |
ProdOptionID | int | Optional | The Product Option ID with which the license was created. When present, the license's Product Option ID will be validated to ensure it matches the value provided in this element. |
UserCode1 | int | Required | The randomized session code value used with Protection PLUS 4 SDK compatible activations. |
UserCode2 | int | Required | The Computer ID number value used with Protection PLUS 4 SDK compatible activations. |
RequireRegistration | bool | Optional | When true, the customer will be required to have registered before allowing activation. If omitted, false is assumed. |
ProductVersion | string | Optional | Product Version Number. This should be formatted like NNNNN.NNNNN.NNNNN.NNNNN, where each N represents a digit (leading zeroes are not required). |
InstallationName | string | Optional | Descriptive name for the installation. |
InstallationID | string | Optional | Existing InstallationID. When provided, this will be stored as the RelatedInstallationID on the activation record. |
ActivationData | string | Optional | An string containing an XML document that has activation data. This XML document typically contains data which is used to uniquely identify the system which is being activated. If used, a valid XML document must be provided, which must have a single, root node. |
The input XML is in the following format:
- XML
- <ActivateInstallation xmlns="">
<EncryptionKeyID></EncryptionKeyID></ActivateInstallation>
<PrivateData><LicenseID></LicenseID></PrivateData>
<Password></Password>
<SerialNumber></SerialNumber>
<ProdOptionID></ProdOptionID>
<UserCode1></UserCode1>
<UserCode2></UserCode2>
<RequireRegistration></RequireRegistration>
<ProductVersion></ProductVersion>
<LicenseID></LicenseID>
<InstallationName></InstallationName>
<InstallationID></InstallationID>
<ActivationData><XmlDocument/></ActivationData>
Output
The result is returned as XML in the following format:
- XML
- <ActivateInstallation>
<PrivateData></ActivateInstallation><ResultCode></ResultCode></PrivateData>
<ErrorMessage></ErrorMessage>
<ExtendedResultCode></ExtendedResultCode>
<ExtendedErrorMessage></ExtendedErrorMessage>
<Product></Product>
<LicenseID></LicenseID>
<Quantity></Quantity>
<RegistrationKey1></RegistrationKey1>
<RegistrationKey2></RegistrationKey2>
<LicenseUpdate></LicenseUpdate>
<ActivationsLeft></ActivationsLeft>
<ExpirationDate></ExpirationDate>
<InstallationID></InstallationID>
<ActivationPassword></ActivationPassword>
<IsTestLicense></IsTestLicense>
<LicenseStatus></LicenseStatus>
<MinimumActivationVersionString></MinimumActivationVersionString>
<MinimumActivationVersionLong></MinimumActivationVersionLong>
<MinimumActivationVersionUrl></MinimumActivationVersionUrl>
<ServerDateTime></ServerDateTime>
<SessionCode></SessionCode>
The values of these elements are as follows:
Parameter | Data Type | Description |
---|---|---|
ResultCode | int | May contain one of the following values, each of which indicates a possible result:
|
ErrorMessage | string | Detailed error message for the result code. Only returned in error conditions (a non-zero ResultCode) |
ExtendedResultCode | int | Extended result code returned by an activation plugin which failed. Only returned when an activation plugin is configured and returns a failure result. |
ExtendedErrorMessage | string | Detailed error message for the ExtendedResultCode. Only returned when an activation plugin is configured and returns a failure result and an extended error message. |
Product | string | Full Product Name (product and option name). Only returned if activation is successful or declined when no activations are left (ResultCode 0 and 5013). |
LicenseID | int | The License ID of the license being activated. Only returned if activation is successful or declined when no activations are left (ResultCode 0 and 5013). |
Quantity | int | License Quantity. Only returned if activation is successful or declined when no activations are left (ResultCode 0 and 5013). |
ActivationsLeft | int | License Activations Left (after current activation). Only returned if activation is successful or declined due to no more keys (ResultCode 0 and 5013) |
RegistrationKey1 | int | Registration Key 1/Activation Code 1. Only returned if activation is successful (ResultCode 0). |
RegistrationKey2 | string | Registration Key 2/Activation Code 2. Only returned if activation is successful (ResultCode 0) and the Product Option Type is an "Activation Code" type that includes a secondary value (such as the Fixed Value, Quantity, or Days Left). |
LicenseUpdate | string | License update string. Only returned if activation is successful (ResultCode 0) and a value is populated on the license. |
ExpirationDate | date | License and/or download expiration date. Only returned if activation is successful (ResultCode 0) and the Product Option is configured to use an expiration date (Days To D/L > 0). |
InstallationID | string | The Installation ID which uniquely identifies the successful activation. Only returned if activation is successful (ResultCode 0) and Issue Installation ID setting is enabled in the Product Option configuration. |
ActivationPassword | string | License activation password. Only returned if activation is successful (ResultCode 0). |
IsTestLicense | bool | Whether to mark the license as a test license. On SOLO Server Shared and Dedicated URL, test licenses are automatically purged on the first of every month so they are not billed. |
LicenseStatus | string | License status. Only returned if license status in not OK (ResultCode 5017). |
MinimumActivationVersionString | string | Minimum product version required for activation (string representation). Only returned if activation version check fails (result code 5012). |
MinimumActivationVersionLong | long | Minimum product version required for activation (long integer representation). Only returned if activation version check fails (ResultCode 5012). |
MinimumActivationVersionUrl | string | Url for more information or to download the update. Only returned if activation version check fails (ResultCode 5012) and a Minimum Activation URL has been specified in the Product Option configuration. |
ServerDateTime | dateTime | Server timestamp. |
SessionCode | string | A session code generated by the client to prevent replay attacks. |
The documentation files for this Web method are as follows:
- ActivateInstallationInput.xml
- ActivateInstallationInputDetails.xml
- ActivateInstallationInput.xsd
- ActivateInstallationOutput.xml
- ActivateInstallationOutputDetails.xml
- ActivateInstallationOutput.xsd
ActivateInstallationLicenseFile
This web method is used to perform an activation for an installation on a given license using the Protection PLUS 5 SDKlibraries. It returns activation codes, other license information related to activation, and an encrypted and digitally signed XML License File.
Any new or existing Protection PLUS customers who are creating a new application may want to consider evaluating this new system. Contact us for more information.
The values of these elements are as follows:
Parameter | Data Type | Required/Optional | Description |
---|---|---|---|
EncryptionKeyID | string | Required |
The Encryption Key ID used for encrypting, decrypting, digitally signing, and verifying requests and responses. This is included in the Encryption Envelope, which may be retrieved by clicking the Configure/Products menu and clicking Actions/View Encryption Key Data. |
LicenseID | int | Required for LicenseID/Password authentication, otherwise optional. | The LicenseID to activate. |
Password | string | Required for LicenseID/Password authentication, otherwise optional. | For LicenseID/Password authentication, the customer password or license activation password. If provided for SerialNumber/ProductID validation, the customer password, license activation password, or for Assigned from List serials, the serial number password. |
SerialNumber | string | Required for SerialNumber/ProductID authentication, otherwise optional. | The Serial Number to activate. |
ProductID | int | Required with SerialNumber/ProductID authentication, otherwise optional. | The License ProductID. When present, the License ProductID will be validated against this ProductID. Multiple ProductID elements can be included, in which case the License ProductID will be validated against a list. |
ProdOptionID | int | Optional | The License Product Option ID. When present, the License Product Option ID will be validated against this Product Option ID. |
UserCode1 | int | Required | The randomized session code value used with Protection PLUS 4 SDK compatible activations. |
UserCode2 | int | Required | The Computer ID number value used with Protection PLUS 4 SDK compatible activations. |
RequireRegistration | bool | Optional | When true, the customer will be required to have registered before allowing activation. If omitted, false is assumed. |
ProductVersion | string | Optional | Product Version Number. This should be formatted like NNNNN.NNNNN.NNNNN.NNNNN, where each N represents a digit (leading zeroes are not required). |
InstallationName | string | Optional | Descriptive name for the installation. |
InstallationID | string | Optional | Existing InstallationID. When provided, this will be stored as the RelatedInstallationID on the activation record. |
ActivationData | XmlDocument | Optional | An string containing an XML document that has activation data. This XML document typically contains data which is used to uniquely identify the system which is being activated. If used, a valid XML document must be provided, which must have a single, root node. |
The input xml is in the following format:
- XML
- <ActivateInstallationLicenseFile xmlns="">
<EncryptionKeyID></EncryptionKeyID></ActivateInstallationLicenseFile>
<PrivateData><LicenseID></LicenseID></PrivateData>
<Password></Password>
<SerialNumber></SerialNumber>
<ProductID></ProductID>
<ProdOptionID></ProdOptionID>
<UserCode1></UserCode1>
<UserCode2></UserCode2>
<RequireRegistration></RequireRegistration>
<ProductVersion></ProductVersion>
<InstallationName></InstallationName>
<InstallationID></InstallationID>
<ActivationData><XmlDocument/></ActivationData>
Output
The result is returned as XML in the following format:
- XML
- <ActivateInstallationLicenseFile>
<EncryptionKeyID></EncryptionKeyID></ActivateInstallationLicenseFile>
<PrivateData><ResultCode></ResultCode></PrivateData>
<ErrorMessage></ErrorMessage>
<ExtendedResultCode></ExtendedResultCode>
<ExtendedErrorMessage></ExtendedErrorMessage>
<Product></Product>
<LicenseID></LicenseID>
<Quantity></Quantity>
<RegistrationKey1></RegistrationKey1>
<RegistrationKey2></RegistrationKey2>
<LicenseUpdate></LicenseUpdate>
<ActivationsLeft></ActivationsLeft>
<ExpirationDate></ExpirationDate>
<InstallationID></InstallationID>
<ActivationPassword></ActivationPassword>
<IsTestLicense></IsTestLicense>
<LicenseStatus></LicenseStatus>
<MinimumActivationVersionString></MinimumActivationVersionString>
<MinimumActivationVersionLong></MinimumActivationVersionLong>
<MinimumActivationVersionUrl></MinimumActivationVersionUrl>
<License></License>
<ServerDateTime></ServerDateTime>
<SessionCode></SessionCode>
The values of these elements are as follows:
Parameter | Data Type | Description |
---|---|---|
ResultCode | int | Can take the following values
|
ErrorMessage | string | Detailed error message for the ResultCode. Only returned in error conditions (ResultCode non zero) |
ExtendedResultCode | int | Extended result code returned by an activation plugin which failed. Only returned when an activation plugin is configured and returns a failure result. |
ExtendedErrorMessage | string | Detailed error message for the ExtendedResultCode. Only returned when an activation plugin is configured and returns a failure result and an extended error message. |
Product | int | Full Product Name (product and option name). Only returned if activation is successful or declined due to no more keys (ResultCodes 0, 5013). |
LicenseID | int | LicenseID; Only returned if activation is successful or declined due to no more keys (ResultCode 0 and 5013). |
Quantity | int | License Quantity. Only returned if activation is successful or declined due to no more keys (ResultCode 0 and 5013). |
ActivationsLeft | int | License Activations Left (after current activation). Only returned if activation is successful or declined due to no more keys (ResultCode 0 and 5013) |
RegistrationKey1 | int | Registration Key 1. Only returned if activation is successful (ResultCode 0). |
RegistrationKey2 | string | Registration Key 2/Activation Code 2. Only returned if activation is successful (ResultCode 0) and the Product Option Type is an "Activation Code" type that includes a secondary value (such as the Fixed Value, Quantity, or Days Left). |
LicenseUpdate | string | License Update string. Only returned if activation is successful (ResultCode 0) and value is populated on the license. |
ExpirationDate | date | License expiration Date. Only returned if activation is successful (ResultCode 0) and the ProdOption is set for expiration (Days To D/L > 0). |
InstallationID | string | The Installation ID which uniquely identifies the successful activation. Only returned if activation is successful (ResultCode 0) and Issue Installation ID setting is enabled in the Product Option configuration. |
ActivationPassword | string | License activation password. Only returned if activation is successful (ResultCode 0). |
IsTestLicense | bool | Whether to mark the license as a test license. On SOLO Server Shared and Dedicated URL, test licenses are automatically purged on the first of every month so they are not billed. |
LicenseStatus | string | License status. Only returned if license status in not OK (ResultCode 5017). |
MinimumActivationVersionString | string | Minimum product version required for activation (string representation). Only returned if activation version check fails (ResultCode 5012). |
MinimumActivationVersionLong | long | Minimum product version required for activation (long integer representation). Only returned if activation version check fails (ResultCode 5012). |
MinimumActivationVersionUrl | string | Url for more information or to download the update. Only returned if activation version check fails (ResultCode 5012) and a Minimum Activation URL has been specified in the Product Option configuration. |
License | string | The contents of the XML License File. When encryption is being used for this file, it will be in its encrypted form here. |
ServerDateTime | dateTime | Server timestamp. |
SessionCode | string | A session code generated by the client to prevent replay attacks. |
The documentation files for this Web method are as follows:
- ActivateInstallationLicenseFileInput.xml
- ActivateInstallationLicenseFileInputDetails.xml
- ActivateInstallationLicenseFileInput.xsd
- ActivateInstallationLicenseFileOutput.xml
- ActivateInstallationLicenseFileOutputDetails.xml
- ActivateInstallationLicenseFileOutput.xsd
DeactivateInstallation
This web method is used to deactivate an installation activated through the ActivateInstallation or ActivateInstallationLicenseFile web methods.
Input
The values of these elements are as follows:
Parameter | Data Type | Required/Optional | Description |
---|---|---|---|
EncryptionKeyID | string | Required |
The Encryption Key ID used for encrypting, decrypting, digitally signing, and verifying requests and responses. This is included in the Encryption Envelope, which may be retrieved by clicking the Configure/Products menu and clicking Actions/View Encryption Key Data. |
InstallationID | string | Required | The InstallationID to deactivate. |
The input xml is in the following format:
- XML
- <DeactivateInstallation xmlns="">
<EncryptionKeyID></EncryptionKeyID></DeactivateInstallation>
<PrivateData><InstallationID></InstallationID></PrivateData>
Output
The result is returned as XML in the following format:
- XML
- <DeactivateInstallation>
<PrivateData></DeactivateInstallation><ResultCode></ResultCode></PrivateData>
<ErrorMessage></ErrorMessage>
<DeactivatedDate></DeactivatedDate>
<ServerDateTime></ServerDateTime>
<SessionCode></SessionCode>
The values of these elements are as follows:
Parameter | Data Type | Description |
---|---|---|
ResultCode | int | Can take the following values
|
ErrorMessage | string | Detailed error message for the ResultCode. Only returned in error conditions (ResultCode non zero) |
DeactivatedDate | date | Date the Installation was Deactivated. Only returned when the installation is already deactivated (ResultCode 5016). |
ServerDateTime | dateTime | Server timestamp. |
SessionCode | string | A session code generated by the client to prevent replay attacks. |
The documentation files for this Web method are as follows:
- DeactivateInstallationInput.xml
- DeactivateInstallationInputDetails.xml
- DeactivateInstallationInput.xsd
- DeactivateInstallationOutput.xml
- DeactivateInstallationOutputDetails.xml
- DeactivateInstallationOutput.xsd
CheckInstallationStatus
This web method is used to retrieve installation status information for installations activated through the ActivateInstallation Web method, as well as to optionally post usage data to be logged on the server.
Input
The values of these elements are as follows:
Parameter | Data Type | Required/Optional | Description |
---|---|---|---|
EncryptionKeyID | string | Required |
The Encryption Key ID used for encrypting, decrypting, digitally signing, and verifying requests and responses. This is included in the Encryption Envelope, which may be retrieved by clicking the Configure/Products menu and clicking Actions/View Encryption Key Data. |
InstallationID | string | Required | The InstallationID to check status for. |
ProductVersion | string | Optional | Product Version Number. This should be formatted like NNNNN.NNNNN.NNNNN.NNNNN, where each N represents a digit (leading zeroes are not required). |
To optionally log usage data, include an additional UsageData element. Within this element, include any number of LogEntry elements, which have the following parameters:.
Parameter | Data Type | Required/Optional | Description |
---|---|---|---|
EnteredDate | dateTime | Required | Date/time the event was logged. |
LogSessionID | GUID | Required | GUID session identifier for the application instance. |
Event | string | Required | Event descriptor. |
EventData | string | Optional | Additional data regarding the event. |
NetBIOSName | string | Optional | NetBIOS machine name of the computer. |
DNSName | string | Optional | DNS machine name of the computer. |
UserName | string | Optional | User name of logged in user. |
ApplicationName | string | Optional | Application which logged the event. |
The input xml is in the following format:
- XML
- <CheckInstallationStatus xmlns="">
<EncryptionKeyID></EncryptionKeyID></CheckInstallationStatus>
<PrivateData>
<InstallationID></InstallationID></PrivateData>
<ProductVersion></ProductVersion>
<UsageLog>
<UsageLog></UsageLog>
<LogEntry></UsageLog>
<EnteredDate></EnteredDate></LogEntry>
<LogSessionID></LogSessionID>
<Event></Event>
<EventData></EventData>
<NetBIOSName></NetBIOSName>
<DNSName></DNSName>
<UserName></UserName>
<ApplicationName></ApplicationName>
Output
The result is returned as XML in the following format:
- XML
- <CheckInstallationStatus>
<PrivateData></CheckInstallationStatus><ResultCode></ResultCode></PrivateData>
<ErrorMessage></ErrorMessage>
<DeactivatedDate></DeactivatedDate>
<LicenseStatus></LicenseStatus>
<LicenseUpdate></LicenseUpdate>
<ExpirationDate></ExpirationDate>
<RemainingActivations></RemainingActivations>
<ServerDateTime></ServerDateTime>
<SessionCode></SessionCode>
The values of these elements are as follows:
Parameter | Data Type | Description |
---|---|---|
ResultCode | int | Can take the following values
|
ErrorMessage | string | Detailed error message for the ResultCode. Only returned in error conditions (ResultCode non zero). |
DeactivatedDate | date | Date the Installation was Deactivated. Only returned if the installation is deactivated (ResultCode 5016). |
LicenseStatus | string | Current license status. Only returned if license status is not valid (ResultCode 5017). |
LicenseUpdate | string | License Update string. Only returned if the value on the license is populated. |
ExpirationDate | date | License expiration Date. Only returned if Product Option is set for expiration (Days To D/L > 0). |
RemainingActivations | int | The number of activations remaining on the license. |
ServerDateTime | dateTime | Server timestamp. |
SessionCode | string | A session code generated by the client to prevent replay attacks. |
The documentation files for this Web method are as follows:
- CheckInstallationStatusInput.xml
- CheckInstallationStatusInputDetails.xml
- CheckInstallationStatusInput.xsd
- CheckInstallationStatusOutput.xml
- CheckInstallationStatusOutputDetails.xml
- CheckInstallationStatusOutput.xsd
DecrementLicenseCounter
This web method is used to decrement the license counter on the license for a given installation.
Input
The values of these elements are as follows:
Parameter | Data Type | Required/Optional | Description |
---|---|---|---|
EncryptionKeyID | string | Required |
The Encryption Key ID used for encrypting, decrypting, digitally signing, and verifying requests and responses. This is included in the Encryption Envelope, which may be retrieved by clicking the Configure/Products menu and clicking Actions/View Encryption Key Data. |
InstallationID | string | Required | The InstallationID to decrement the license counter for. |
DecrementAmount | int | Required | The amount to decrement the license counter by. |
The input xml is in the following format:
- XML
- <DecrementLicenseCounter xmlns="">
<EncryptionKeyID></EncryptionKeyID></DecrementLicenseCounter>
<PrivateData>
<InstallationID></InstallationID></PrivateData>
<DecrementAmount></DecrementAmount>
Output
The result is returned as XML in the following format:
- XML
- <DecrementLicenseCounter>
<PrivateData></DecrementLicenseCounter><ResultCode></ResultCode></PrivateData>
<ErrorMessage></ErrorMessage>
<LicenseCounter></LicenseCounter>
<DeactivatedDate></DeactivatedDate>
<LicenseStatus></LicenseStatus>
<ServerDateTime></ServerDateTime>
<SessionCode></SessionCode>
The values of these elements are as follows:
Parameter | Data Type | Description |
---|---|---|
ResultCode | int | Can take the following values
|
ErrorMessage | string | Detailed error message for the ResultCode. Only returned in error conditions (ResultCode non zero). |
LicenseCounter | int | On success (ResultCode 0), the new value of the license counter after decrementing. On failure (ResultCode non-zero), the existing value of the license counter, if available. |
DeactivatedDate | date | Date the Installation was Deactivated. Only returned if the installation is deactivated (ResultCode 5016). |
LicenseStatus | string | Current license status. Only returned if license status is not valid (ResultCode 5017). |
ServerDateTime | dateTime | Server timestamp. |
SessionCode | string | A session code generated by the client to prevent replay attacks. |
The documentation files for this Web method are as follows: