License Creation/Renewal/Upgrade Request
The Create new, Renew and Upgrade scenarios use the same request format.
- Create new is needed to create new license keys.
- Renew is needed to prolong license keys.
- Upgrade scenario is needed when multiple sales options are available and it is necessary to switch between them.
Request
The HTTP POST request is made for a specified endpoint with the following parameters:
| Name | Size (Characters) | Description |
|---|---|---|
| APS_PROTOCOL_MODEL | 1 |
2 - Standard implementation is expected. 3 - With reporting implementation with Get License Key Info Request support is expected. When this field is absent, Standard (2) must be assumed. |
| APS_ACTION | up to 30 |
|
| APS_TEST_MODE | 1 |
Y means that the order is a test one. The license key generated must not be accounted towards the billing report; it could be a fake one though issuing a key that can be successfully installed into an application is advised. N or missing this field means that the order is real. |
| ACTIVATION_DATA | unlimited |
Activation data is a packet of tech data required to obtain a valid application license. This parameter is specific to every extension. Some examples of activation data include:
This parameter is optional. You can omit it if the license does not require any activation data. |
| PURCHASE_ID | up to 10 |
KA license number (without prefix and version). Example: If the full license number is EXT.00123456.0012, then only 00123456 will be passed in this field. |
| PRODUCT_ID | up to 30 |
ID/SKU of the product purchased. The ISV endpoint should be aware of this ID/SKU in order to distinguish between various products (if multiple products are offered). |
| PURCHASE_DATE | 10 |
The date of purchase in the format DD/MM/YYYY, e.g., 12/03/2016. This date corresponds to the date when the current license key action has been initiated, with no regard to the license validity date or initial subscription date. |
| SUBSCRIPTION_DATE | 10 |
Date of subscription (the DD/MM/YYYY format). This date indicates the original date when the license key has been created. When an existing license is upgraded or renewed, this date would stay the same, while the PURCHASE_DATE will change. |
| START_DATE | 10 |
Start date of the current re-billing period (the DD/MM/YYYY format). In KA this is the start date of the license key validity period. In case of a renew request, START_DATE will be different from what was sent in the first license creation request for the same PURCHASE_ID. |
| EXPIRY_DATE | 10 |
Expiry date (date of the next re-billing) (the DD/MM/YYYY format). This is the next re-billing deadline; KA calculates it by adding the update period (1 calendar month) and the grace period (10 days) to the START_DATE. In case of a renew request, EXPIRY_DATE will be different from what was sent in the first license creation request for the same PURCHASE_ID. |
| PREVIOUS_LICENSE_BODY | unlimited |
This parameter holds the license body that was previously saved in KA. The license body is encoded in BASE64. This parameter is passed only with the RENEW and UPGRADE requests. |
| REG_NAME | up to 100 | Internal ID of the license owner in KA. |
Notes:
- Ordering of the fields is not guaranteed.
- Additional fields might be added in future. In case an unknown field is encountered while processing the request, the implementation should ignore it (i.e., process the request as if such field is absent).
Response
In case the request is successfully processed, the implementation should send the response with the status code 200 OK. The following table describes the data returned in the successful response:
| Location | Meaning | Comments |
|---|---|---|
| Response body | License body |
The license body data must be delivered to the ISV application in exactly the same form as provided in the response body. No transformations are permitted regardless of the content type. The exact format of the body should be defined by ISV (can be binary or any kind of textual data - does not matter). The ISV application should be able to recognize this body as a valid key to unlock certain functionality for the end user. |
| X-APS-Expiration-Date response header |
Expiration date (HTTP Date, RFC 1123) |
The ISV endpoint must return expiration date for the generated license key. The ISV endpoint should return the date matching the one requested in the EXPIRY_FIELD. The expiration date specified in the response should be always used instead of the one requested. |
In case the request fails, the implementation should return the appropriate status code and a brief explanation of the reasons of the failure.
The recommended response codes are:
| Status Code | Possible Reasons | KA Responsibility |
|---|---|---|
| 200 OK | The license key generation is successful | Get the license body from the response, wrap it appropriately and deliver to the ISV application. |
| 400 Bad Request |
|
Return the appropriate failure message to the party that issued the original request. |
| 401 Unauthorized | KA did not send an appropriate authentication header | Normally, should not be observed. |
| 403 Forbidden | Authorization failed | Return an appropriate failure message to the administrator responsible for the integration and to the party that issued the original request. |
| 4xx | Any other issue with the request | Return the appropriate failure message to the party that issued the original request. |
| 5xx | Server error | Return the appropriate failure message to the party that issued the original request. |
Examples
Correct PURCHASE request:
POST /handler.php HTTP/1.1
Accept: */*
Content-Type: application/x-www-form-urlencoded
Host: isv.endpoint.example.org
Authorization: Basic am9objpxd2UxMjM=
APS_PROTOCOL_MODEL=2&APS_ACTION=PURCHASE&APS_TEST_MODE=N&PURCHASE_ID=12345678&PRODUCT_ID=someproduct1&PURCHASE_DATE=12%5c03%5c2016&SUBSCRIPTION_DATE=12%5c03%5c2016&START_DATE=12%5c03%5c2016&EXPIRY_DATE=22%5c04%5c2016®_NAME=54321
Successful PURCHASE response with a binary license body:
HTTP/1.1 200 OK
Date: Thu, 12 Mar 2016 15:02:10 GMT
Server: Web Server
X-APS-Expiration-Date: Fri, 22 Apr 2016 15:02:10 GMT
Content-Type: application/octet-stream
<response body bytes go here>
Correct RENEW request:
POST /handler.php HTTP/1.1
Accept: */*
Content-Type: application/x-www-form-urlencoded
Host: isv.endpoint.example.org
Authorization: Basic am9objpxd2UxMjM=
APS_PROTOCOL_MODEL=2&APS_ACTION=RENEW&APS_TEST_MODE=N&PURCHASE_ID=12345678&PRODUCT_ID=someproduct1&PURCHASE_DATE=12%5c04%5c2016&SUBSCRIPTION_DATE=12%5c03%5c2016&START_DATE=12%5c04%5c2016&EXPIRY_DATE=22%5c05%5c2016&PREVIOUS_LICENSE_BODY=NCA4IDE1IDE2IDIzIDQy®_NAME=54321
Successful RENEW response with a binary license body:
HTTP/1.1 200 OK
Date: Thu, 12 Mar 2016 15:02:10 GMT
Server: Web Server
X-APS-Expiration-Date: Sun, 22 May 2016 15:02:10 GMT
Content-Type: application/octet-stream
<response body bytes go here>
Incorrect request (an invalid EXPIRY_DATE is specified):
POST /handler.php HTTP/1.1
Accept: */*
Content-Type: application/x-www-form-urlencoded
Host: isv.endpoint.example.org
Authorization: Basic am9objpxd2UxMjM=
APS_PROTOCOL_MODEL=2&APS_ACTION=PURCHASE&APS_TEST_MODE=N&PURCHASE_ID=12345678&PRODUCT_ID=someproduct1&PURCHASE_DATE=12%5c03%5c2016&SUBSCRIPTION_DATE=12%5c03%5c2016&START_DATE=12%5c03%5c2016&EXPIRY_DATE=22%5c04%5c2015®_NAME=54321
Error response:
HTTP/1.1 400 Bad Request
Date: Thu, 12 Mar 2016 15:02:10 GMT
Server: Web Server
Content-Type: text/plain; charset=UTF-8
Error: Subscription expiration date cannot be less than subscription start date
Unauthorized response:
HTTP/1.1 401 Unauthorized
Date: Thu, 12 Mar 2016 15:02:10 GMT
Server: Web Server
Content-Type: text/plain; charset=UTF-8
WWW-Authenticate: Basic realm="License Key Generator"
Error: No credentials supplied. Please authorize
Authorization failed response:
HTTP/1.1 403 Forbidden
Date: Thu, 12 Mar 2016 15:02:10 GMT
Server: Web Server
Content-Type: text/plain; charset=UTF-8
Error: Access denied