PUT /authCodes

Use this method to redeem licenses from one or more authorization codes, fetch redeemed license-activation keys, and modify customer information.

You can perform the following management tasks.
  • Redeem licenses for one or more authorization codes

    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.

    If you specify a single authorization code, 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 set licenseKeys.state to not installed.

    If you specify a multiple authorization code, all remaining licenses for the specified authorization codes are redeemed. Use the authCode attribute to identify the license authorization code, and set licenseKeys.state to not installed.

    When you redeem licenses for authorization codes, the license-activation keys are retrieved automatically.

  • Retrieve license keys for one or more authorization codes

    You can manually retrieve license-activation keys from the Features on Demand web portal for a license-authorization code that has redeemed licenses. You must also specify either authorization code or Lenovo customer number set the retrieveKeys attribute to true. If a single license-activation keys is selected, the key is saved as a .KEY file on the local system. If multiple license-activation keys are selected, the license-activation key files are compressed into a ZIP file that is saved on the local system. The file location is returned in the Location field in the response header.

    After retrieving keys, you can then import and install the keys in XClarity Administrator using POST /quantityLicense.

  • Modifying customer information

    You can set new values for customer information by using the customerInfo attributes.

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

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 Required Array of objects Information about each license-authorization code
  authCode Required String License-authorization code ID
  errorMsg Required String Message description

This attribute is idempotent (cannot be changed).

  featureCode Required Integer License feature code

This attribute is idempotent (cannot be changed).

  featureDescription Required String License feature description

This attribute is idempotent (cannot be changed).

  keysRedeemed Required Integer Number of redeemed license-activation keys

This attribute is idempotent (cannot be changed).

  keysRedeemQty Required Integer Number of redeemed license-activation keys
  keysRemaining Required Integer Number of available (not redeemed) license-activation keys

This attribute is idempotent (cannot be changed).

  lenovoCustomerNumber Required String Lenovo customer number
  licenseKeys Required Array of objects Information about each license-activation key
    customerNumber Required String Lenovo customer number associated with the license-activation key
    licenseKeyId Required String License-activation key ID

This attribute is idempotent (cannot be changed).

    quantity Required Integer Number of redeemed licenses
    state Required String License-activation key state

This attribute cannot be changed.

  partNumber Required String License part number

This attribute is idempotent (cannot be changed).

  purchaseOrder Required String License purchase-order number

This attribute is idempotent (cannot be changed).

  retrieveKeys Required 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 Required String License sales-order number

This attribute is idempotent (cannot be changed).

  startDate Required 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).

customerInfo Required Object Information about the customer that is associated with the license-authorization codes
  companyNameInEnglish Required String Customer company name in English
  companyNameInLocalLanguage Required String Customer company name in local language
  contactPhoneNumber Required String Customer phone number
  contactEmailAddress Required String Customer email address
  customerAddress Required String Customer physical address
  customerCity Required String Customer city
  customerRegionStateOrProvince Required String Customer state or region
  customerPostalCode Required String Customer postal code
  country Required String Customer country code
  firstName Required String Customer given name
  lastName Required String Customer family name
  preferredLanguage Required String Preferred language
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": 10,
         "state": "not installed",
      }],
      "partNumber": "",
      "purchaseOrder": "",
      "retrieveKeys": false,
      "salesOrder": "",
      "startDate": "",
   }],
   "customerInfo": {
      "companyNameInEnglish": "",
      "companyNameInLocalLanguage": "",
      "contactPhoneNumber": "",
      "contactEmailAddress": "",
      "customerAddress": "",
      "customerCity": "",
      "customerRegionStateOrProvince": "",
      "customerPostalCode": "",
      "country": "",
      "firstName": "",
      "lastName": "",
      "preferredLanguage": ""
   }
}
The following example redeems all remaining licenses for two authorization codes.
{
   "authCodes": [{
      "authCode": "YYA7BQ2V37V11O0AID2K4",
      "errorMsg": "",
      "featureCode": "",
      "featureDescription": "",
      "keysRedeemed": null,
      "keysRedeemQty": null,
      "keysRemaining ": null,
      "lenovoCustomerNumber": "",
      "licenseKeys": [{
         "customerNumber": "1234567890",
         "licenseKeyId": "",
         "quantity": null,
         "state": "not installed",
      }],
      "partNumber": "",
      "purchaseOrder": "",
      "retrieveKeys": false,
      "salesOrder": "",
      "startDate": "",
   },
   {
      "authCode": "YYA7BQ2V37V11O0AID2K5",
      "errorMsg": "",
      "featureCode": "",
      "featureDescription": "",
      "keysRedeemed": null,
      "keysRedeemQty": null,
      "keysRemaining ": null,
      "lenovoCustomerNumber": "",
      "licenseKeys": [{
         "customerNumber": "1234567890",
         "licenseKeyId": "",
         "quantity": null,
         "state": "not installed",
      }],
      "partNumber": "",
      "purchaseOrder": "",
      "retrieveKeys": false,
      "salesOrder": "",
      "startDate": "",
   }],
   "customerInfo": {
      "companyNameInEnglish": "",
      "companyNameInLocalLanguage": "",
      "contactPhoneNumber": "",
      "contactEmailAddress": "",
      "customerAddress": "",
      "customerCity": "",
      "customerRegionStateOrProvince": "",
      "customerPostalCode": "",
      "country": "",
      "firstName": "",
      "lastName": "",
      "preferredLanguage": ""
   }
}

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 when ten of the remaining licenses in a single authorization code are redeemed
{
   "authCodes": [{
      "authCode": "YYA7BQ2V37V11O0AID2K4",
      "errorMsg": "",
      "featureCode": "1341 contact",
      "featureDescription": "Lenovo XClarity Pro, Per Managed Endpoint w/5 Yr SW S&S",
      "keysRedeemed": 35,
      "keysRemaining ": 15,
      "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"
   }
}
The following example is returned if the request is successful when all remaining licenses for two authorization codes are redeemed.
{
   "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",
   },
   {
      "authCode": "YYA7BQ2V37V11O0AID2K5",
      "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": "00113",
         "quantity": null,
         "state": "not installed"
      },
      {
         "customerNumber": "1234567890",
         "licenseKeyId": "00114",
         "quantity": null,
         "state": "not installed"
      }],
      "partNumber": "5641PX5",
      "purchaseOrder": "00000000",
      "salesOrder": "999999999",
      "startDate": "2020-06-02"
   }],
   "customerInfo": {
      "companyNameInEnglish": "Some Company",
      "companyNameInLocalLanguage": " Some Company ",
      "contactEmailAddress": "jane.doe@somecompany.com",
      "contactPhoneNumber": "9995551212",
      "customerAddress": "10 Main Street",
      "customerCity": "Rockville",
      "customerRegionStateOrProvince": "NY",
      "customerPostalCode": "12345",
      "country": "US",
      "firstName": "Jane",
      "lastName": "Doe",
      "preferredLanguage": "EN"
   }
}