Open topic with navigation

XML Activation Service

Refer to the SOLO Server New Activation Features white paper for more information on these new Web services.

The XML Activation Service Web service provides several activation-related Web methods. For Instant SOLO Server Shared URL, this can be reached at https://secure.softwarekey.com/solo/webservices/XmlActivationService.asmx. If you are using Instant SOLO Server Custom Shared URL or Instant SOLO Server Dedicated URL, replace secure.softwarekey.com with your sub-domain/domain. If you are running a standalone version of SOLO Server, 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.

Important

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:

Important

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:

Please refer to the applicable product manuals and sample projects for more information on each library/API.

Important

Please note that all date values returned by the above Web methods are in UTC time, using the ISO 8601 format as follows:

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. The customer password or license activation 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>
<PrivateData>
<LicenseID></LicenseID>
<Password></Password>
<SerialNumber></SerialNumber>
<ProdOptionID></ProdOptionID>
<UserCode1></UserCode1>
<UserCode2></UserCode2>
<RequireRegistration></RequireRegistration>
<ProductVersion></ProductVersion>
<LicenseID></LicenseID>
<InstallationName></InstallationName>
<InstallationID></InstallationID>
<ActivationData>
<XmlDocument/>
</ActivationData>
</PrivateData>
</ActivateInstallation>

Output

The result is returned as XML in the following format:

XML
<ActivateInstallation>
<PrivateData>
<ResultCode></ResultCode>
<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>
</PrivateData>
</ActivateInstallation>

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:
  • 0 - Success
  • 5000 - Invalid Encryption Key ID
  • 5001 - Encryption Required
  • 5002 - Signature Required
  • 5003 - Decryption Failure
  • 5004 - Verification Failure
  • 5005 - Invalid Parameters
  • 5006 - Security Check Failure
  • 5007 - Invalid Computer ID
  • 5008 - Invalid Activation Data
  • 5009 - Unregistered Customer
  • 5010 - Invalid Product ID
  • 5011 - Invalid Product Option ID
  • 5012 - Invalid Product Version
  • 5013 - No Remaining Activations
  • 5014 - Invalid Option Type
  • 5016 - Deactivated Installation
  • 5017 - Invalid License Status
  • 5019 - License Expired
  • 5021 - Invalid IP Address
  • 5022 - Invalid System Time
  • 5024 - Invalid XML Document
  • 5025 - Plugin Failed
  • 5026 - Plugin Processing Failed
  • 5029 - Invalid Trigger Code Data
  • 5033 - Account Closed
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 the license is marked as a test license. On Instant SOLO Server, 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:

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 that are creating a new application may want to consider evaluating this new system. Contact us for more information.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 LicenseID to activate.
Password string Required for LicenseID/Password authentication, otherwise optional. The customer password or license activation 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>
<PrivateData>
<LicenseID></LicenseID>
<Password></Password>
<SerialNumber></SerialNumber>
<ProductID></ProductID>
<ProdOptionID></ProdOptionID>
<UserCode1></UserCode1>
<UserCode2></UserCode2>
<RequireRegistration></RequireRegistration>
<ProductVersion></ProductVersion>
<InstallationName></InstallationName>
<InstallationID></InstallationID>
<ActivationData>
<XmlDocument/>
</ActivationData>
</PrivateData>
</ActivateInstallationLicenseFile>

Output

The result is returned as XML in the following format:

XML
<ActivateInstallationLicenseFile>
<EncryptionKeyID></EncryptionKeyID>
<PrivateData>
<ResultCode></ResultCode>
<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>
</PrivateData>
</ActivateInstallationLicenseFile>

The values of these elements are as follows:

Parameter Data Type Description
ResultCode int Can take the following values
  • 0 - Success
  • 5000 - Invalid EncryptionKeyID
  • 5001 - Encryption Required
  • 5002 - Signature Required
  • 5003 - Decryption Failure
  • 5004 - Verification Failure
  • 5005 - Invalid Parameters
  • 5006 - Security Check Failure
  • 5007 - Invalid ComputerID
  • 5008 - Invalid Activation Data
  • 5009 - Unregistered Customer
  • 5010 - Invalid ProductID
  • 5011 - Invalid ProdOptionID
  • 5012 - Invalid Product Version
  • 5013 - No Remaining Activations
  • 5014 - Invalid Option Type
  • 5016 - Deactivated Installation
  • 5017 - Invalid License Status
  • 5019 - License Expired
  • 5021 - Invalid IP Address
  • 5022 - Invalid System Time
  • 5023 - Protection PLUS 5 SDK Access Not Enabled
  • 5024 - Invalid Xml Document
  • 5025 - Plugin Failed
  • 5026 - Plugin Processing Failed
  • 5029 - Invalid Trigger Code Data
  • 5030 - Protection PLUS 5 SDK evaluation has expired
  • 5031 - SOLO Server evaluation has expired
  • 5033 - Account Closed
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 the license is marked as a test license. On Instant SOLO Server, 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:

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>
<PrivateData>
<InstallationID></InstallationID>
</PrivateData>
</DeactivateInstallation>

Output

The result is returned as XML in the following format:

XML
<DeactivateInstallation>
<PrivateData>
<ResultCode></ResultCode>
<ErrorMessage></ErrorMessage>
<DeactivatedDate></DeactivatedDate>
<ServerDateTime></ServerDateTime>
<SessionCode></SessionCode>
</PrivateData>
</DeactivateInstallation>

The values of these elements are as follows:

Parameter Data Type Description
ResultCode int Can take the following values
  • 0 - Success
  • 5000 - Invalid EncryptionKeyID
  • 5001 - Encryption Required
  • 5002 - Signature Required
  • 5003 - Decryption Failure
  • 5004 - Verification Failure
  • 5005 - Invalid Parameters
  • 5015 - Invalid InstallationID
  • 5016 - Deactivated Installation
  • 5018 - No Remaining Deactivations
  • 5022 - Invalid System Time
  • 5024 - Invalid Xml Document
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:

CheckInstallationStatus

This Web method is used to retrieve installation status information for installations activated through the ActivateInstallation Web method, as well as to post usage data to be logged on the server. Note that the UsageData element is optional, but if specified can contain any number of LogEntry elements.

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).
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 Required Additional data regarding the event.
NetBIOSName string Required NetBIOS machine name of the computer.
DNSName string Required DNS machine name of the computer.
UserName string Required User name of logged in user.
ApplicationName string Required Application which logged the event.

The input xml is in the following format:

XML
<CheckInstallationStatus xmlns="">
<EncryptionKeyID></EncryptionKeyID>
<PrivateData>
<InstallationID></InstallationID>
<ProductVersion></ProductVersion>
</PrivateData>
<UsageLog>
<UsageLog>
<LogEntry>
<EnteredDate></EnteredDate>
<LogSessionID></LogSessionID>
<Event></Event>
<EventData></EventData>
<NetBIOSName></NetBIOSName>
<DNSName></DNSName>
<UserName></UserName>
<ApplicationName></ApplicationName>
</LogEntry>
</UsageLog>
</UsageLog>
</CheckInstallationStatus>

Output

The result is returned as XML in the following format:

XML
<CheckInstallationStatus>
<PrivateData>
<ResultCode></ResultCode>
<ErrorMessage></ErrorMessage>
<DeactivatedDate></DeactivatedDate>
<LicenseStatus></LicenseStatus>
<LicenseUpdate></LicenseUpdate>
<ExpirationDate></ExpirationDate>
<ServerDateTime></ServerDateTime>
<SessionCode></SessionCode>
</PrivateData>
</CheckInstallationStatus>

The values of these elements are as follows:

Parameter Data Type Description
ResultCode int Can take the following values
  • 0 - Success
  • 5000 - Invalid EncryptionKeyID
  • 5001 - Encryption Required
  • 5002 - Signature Required
  • 5003 - Decryption Failure
  • 5004 - Verification Failure
  • 5005 - Invalid Parameters
  • 5015 - Invalid InstallationID
  • 5016 - Deactivated Installation
  • 5017 - Invalid License Status
  • 5022 - Invalid System Time
  • 5024 - Invalid Xml Document
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).
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: