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 user name 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&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"
   }
}