Skip to main content

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 username 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.

AttributesRequired / OptionalTypeDescription
authCodesRequiredArray of objectsInformation about each license-authorization code
 authCodeRequiredStringLicense-authorization code ID
 errorMsgRequiredStringMessage description

This attribute is idempotent (cannot be changed).

 featureCodeRequiredIntegerLicense feature code

This attribute is idempotent (cannot be changed).

 featureDescriptionRequiredStringLicense feature description

This attribute is idempotent (cannot be changed).

 keysRedeemedRequiredIntegerNumber of redeemed license-activation keys

This attribute is idempotent (cannot be changed).

 keysRedeemQtyRequiredIntegerNumber of redeemed license-activation keys
 keysRemainingRequiredIntegerNumber of available (not redeemed) license-activation keys

This attribute is idempotent (cannot be changed).

 lenovoCustomerNumberRequiredStringLenovo customer number
 licenseKeysRequiredArray of objectsInformation about each license-activation key
  customerNumberRequiredStringLenovo customer number associated with the license-activation key
  licenseKeyIdRequiredStringLicense-activation key ID

This attribute is idempotent (cannot be changed).

  quantityRequiredIntegerNumber of redeemed licenses
  stateRequiredStringLicense-activation key state

This attribute cannot be changed.

 partNumberRequiredStringLicense part number

This attribute is idempotent (cannot be changed).

 purchaseOrderRequiredStringLicense purchase-order number

This attribute is idempotent (cannot be changed).

 retrieveKeysRequiredBooleanIndicates 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.
 salesOrderRequiredStringLicense sales-order number

This attribute is idempotent (cannot be changed).

 startDateRequiredStringDate 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).

customerInfoRequiredObjectInformation about the customer that is associated with the license-authorization codes
 companyNameInEnglishRequiredStringCustomer company name in English
 companyNameInLocalLanguageRequiredStringCustomer company name in local language
 contactPhoneNumberRequiredStringCustomer phone number
 contactEmailAddressRequiredStringCustomer email address
 customerAddressRequiredStringCustomer physical address
 customerCityRequiredStringCustomer city
 customerRegionStateOrProvinceRequiredStringCustomer state or region
 customerPostalCodeRequiredStringCustomer postal code
 countryRequiredStringCustomer country code
 firstNameRequiredStringCustomer given name
 lastNameRequiredStringCustomer family name
 preferredLanguageRequiredStringPreferred 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​

CodeDescriptionComments
200OKThe request completed successfully.
400Bad RequestA 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.
403ForbiddenThe 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.
409ConflictThere is a conflict with the current state of the resource. A descriptive error message is returned in the response body.
500Internal Server ErrorAn internal error occurred. A descriptive error message is returned in the response body.

Response body​

AttributesTypeDescription
authCodesArray of objectsInformation about each license-authorization code
 authCodeStringLicense-authorization code ID
 errorMsgStringMessage description
 featureCodeStringLicense feature code
 featureDescriptionStringLicense feature description
 keysRedeemedIntegerNumber of redeemed license-activation keys
 keysRemainingIntegerNumber of available (not redeemed) license-activation keys
 lenovoCustomerNumberStringLenovo customer number
 licenseKeysArray of objectsInformation about each license-activation key
  customerNumberStringLenovo customer number associated with the license-activation key
  licenseKeyIdStringLicense-activation key ID
  quantityIntegerNumber of redeemed licensees
  stateStringLicense-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.
 partNumberStringLicense part number
 purchaseOrderStringLicense purchase-order number
 salesOrderStringLicense sales-order number
 startDateStringDate 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.

customerInfoObjectInformation about the customer that is associated with the license-authorization codes
 companyNameInEnglishStringCustomer company name in English
 companyNameInLocalLanguageStringCustomer company name in local language
 contactPhoneNumberStringCustomer phone number
 contactEmailAddressStringCustomer email address
 customerAddressStringCustomer physical address
 customerCityStringCustomer city
 customerRegionStateOrProvinceStringCustomer state or region
 customerPostalCodeStringCustomer postal code
 countryStringCustomer country code

For a complete list of country codes, use GET /licenseCountries.

 firstNameStringCustomer given name
 lastNameStringCustomer family name
 preferredLanguageStringLanguage 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"
   }
}