PUT /authCodes/`{code}`

Use this method to redeem licenses from a single authorization code.

Lenovo XClarity Administrator sends a request to the Features on Demand web portal to redeem the licenses. The web portal creates a license-key file for each authorization code and downloads the files to the management server. Each license-key file contains the set of redeemed licenses for a specific authorization code. You can then use the license-key file to apply licenses to the current XClarity Administrator, or you can import and install the downloaded license key file into another XClarity Administrator that might not have access to the Features on Demand web portal.

You can redeem all or a subset of licenses by specifying the keysRedeemQty request attribute. You must also specify the authCode attribute, lenovoCustomerNumber attribute, and ensure that licenseKeys.state is set to not installed..

Note

This REST API requires Lenovo XClarity Administrator v3.5.0 or later.

Authentication

Authentication with username and password is required.

Request URL

PUT https://{management_server_IP}/authCodes/{code}

where {code} is the authorization code ID which was sent to you in an electronic proof of entitlement email when you purchased the licenses.

Query parameters

None

Request body

This request updates the entire resource. If an optional attribute is set to an empty string, that attribute is not changed. If an idempotent (unchangeable) attribute is modified, an error is thrown.

Attributes			Required / Optional	Type	Description
authCodes			Optional	Object	Information about a single license-authorization code
	authCode		Optional	String	License-authorization code ID
	errorMsg		Optional	String	Message description This attribute is idempotent (cannot be changed).
	featureCode		Optional	String	License feature code This attribute is idempotent (cannot be changed).
	featureDescription		Optional	String	License feature description This attribute is idempotent (cannot be changed).
	keysRedeemed		Optional	Integer	Number of redeemed license-activation keys This attribute is idempotent (cannot be changed).
	keysRedeemQty		Optional	Integer	Number of redeemed license-activation keys
	keysRemaining		Optional	Integer	Number of available (not redeemed) license-activation keys This attribute is idempotent (cannot be changed).
	lenovoCustomerNumber		Optional	String	Lenovo customer number
	licenseKeys		Optional	Array of objects	Information about each license-activation key
		customerNumber	Optional	String	Lenovo customer number associated with the license-activation key
		licenseKeyId	Optional	String	License-activation-key ID This attribute is idempotent (cannot be changed).
		quantity	Optional	Integer	Number of redeemed licenses
		state	Optional	String	License-activation key state This attribute cannot be changed.
	partNumber		Optional	String	License part number This attribute is idempotent (cannot be changed).
	purchaseOrder		Optional	String	License purchase-order number This attribute is idempotent (cannot be changed).
	retrieveKeys		Optional	Boolean	Indicates whether to retrieve license-activation keys. This can be one of the following values. true. Retrieve license-activation keys. false. (default) Do not retrieve license-activation keys.
	salesOrder		Optional	String	License sales-order number This attribute is idempotent (cannot be changed).
	startDate		Optional	String	Date when the authorization code was created and the license validation period starts This date is specified using ISO-8601 format (for example, 2019-05-02). For information about ISO-8601 format, see the W3C Date and Time Formats webpage. This attribute is idempotent (cannot be changed).

The following example redeems ten of the remaining licenses in an authorization code.

{
   "authCodes": [{
      "authCode": "YYA7BQ2V37V11O0AID2K4",
      "errorMsg": "",
      "featureCode": "",
      "featureDescription": "",
      "keysRedeemed": null,
      "keysRedeemQty": "10",
      "keysRemaining ": null,
      "lenovoCustomerNumber": "1234567890",
      "licenseKeys": [{
         "customerNumber": "1234567890",
         "licenseKeyId": "",
         "quantity": null,
         "state": "not installed",
      }],
      "partNumber": "",
      "purchaseOrder": "",
      "retrieveKeys": false,
      "salesOrder": "",
      "startDate": "",
   }]
}

Response codes

Code	Description	Comments
200	OK	The request completed successfully.
400	Bad Request	A query parameter or request attribute is missing or not valid, or the operation is not supported. A descriptive error message is returned in the response body.
403	Forbidden	The orchestrator server was prevented from fulfilling the request. A descriptive error message is returned in the response body. Ensure that you have privileges to perform the request.
409	Conflict	There is a conflict with the current state of the resource. A descriptive error message is returned in the response body.
500	Internal Server Error	An internal error occurred. A descriptive error message is returned in the response body.

Response body

Attributes			Type	Description
authCodes			Array of objects	Information about each license-authorization code
	authCode		String	License-authorization code ID
	errorMsg		String	Message description
	featureCode		String	License feature code
	featureDescription		String	License feature description
	keysRedeemed		Integer	Number of redeemed license-activation keys
	keysRemaining		Integer	Number of available (not redeemed) license-activation keys
	lenovoCustomerNumber		String	Lenovo customer number
	licenseKeys		Array of objects	Information about each license-activation key
		customerNumber	String	Lenovo customer number associated with the license-activation key
		licenseKeyId	String	License-activation key ID
		quantity	Integer	Number of redeemed licensees
		state	String	License-activation key state. This can be one of the following values. installed. The license-activation key is installed in XClarity Administrator. not installed. The license-activation key is not installed.
	partNumber		String	License part number
	purchaseOrder		String	License purchase-order number
	salesOrder		String	License sales-order number
	startDate		String	Date when the authorization code was created and the license validation period starts This date is specified using ISO-8601 format (for example, 2019-05-02). For information about ISO-8601 format, see the W3C Date and Time Formats webpage.
customerInfo			Object	Information about the customer that is associated with the license-authorization codes
	companyNameInEnglish		String	Customer company name in English
	companyNameInLocalLanguage		String	Customer company name in local language
	contactPhoneNumber		String	Customer phone number
	contactEmailAddress		String	Customer email address
	customerAddress		String	Customer physical address
	customerCity		String	Customer city
	customerRegionStateOrProvince		String	Customer state or region
	customerPostalCode		String	Customer postal code
	country		String	Customer country code For a complete list of country codes, use GET /licenseCountries.
	firstName		String	Customer given name
	lastName		String	Customer family name
	preferredLanguage		String	Language code of the preferred language For a complete list of language codes, use GET /licenseCountries.

The following example is returned if the request is successful.

{
   "authCodes": [{
      "authCode": "YYA7BQ2V37V11O0AID2K4",
      "errorMsg": "",
      "featureCode": "1341 contact",
      "featureDescription": "Lenovo XClarity Pro, Per Managed Endpoint w/5 Yr SW S&amp;S",
      "keysRedeemed": 50,
      "keysRemaining ": 0,
      "lenovoCustomerNumber": "1234567890",
      "licenseKeys": [{
         "customerNumber": "1234567890",
         "licenseKeyId": "00001",
         "quantity": null,
         "state": "not installed",
      },
      {
         "customerNumber": "1234567890",
         "licenseKeyId": "00002",
         "quantity": null,
         "state": "not installed",
      }],
      "partNumber": "5641PX5",
      "purchaseOrder": "00000000",
      "salesOrder": "999999999",
      "startDate": "2020-06-02",
   }],
   "customerInfo": {
      "companyNameInEnglish": "Some Company",
      "companyNameInLocalLanguage": " Some Company ",
      "contactPhoneNumber": "9995551212",
      "contactEmailAddress": "jane.doe@somecompany.com",
      "customerAddress": "10 Main Street",
      "customerCity": "Rockville",
      "customerRegionStateOrProvince": "NY",
      "customerPostalCode": "12345",
      "country": "US",
      "firstName": "Jane",
      "lastName": "Doe",
      "preferredLanguage": "EN"
   }
}

Give documentation feedback

PUT /authCodes/{code}

Authentication​

Request URL​

Query parameters​

Request body​

Response codes​

Response body​