RegKey Pool Offerings

Overview

You can use this API to add, activate, or remove registration keys from an existing RegKey pool. Each RegKey pool can contain an arbitrary number of BIG-IP registration keys. A RegKey pool typically contains a single type of registration key. Each registration key represents a license offering of the RegKey pool. You can use the RegKey Pool API to create a RegKey pool. You can assign activated registration keys from the RegKey pool and revoke keys from a BIG-IP using the RegKey Pool Members API or the License Assign/Revoke API. If you intend on using automatic activation, your BIG-IQ requires an internet connection to the F5 licensing server. You require the administrator, device manager, or license manager role to use this API.

In the following documentation, {id} is a placeholder which represents an identifier for an existing RegKey pool. And {regkey} represents an identifier for a specific registration key.

REST Endpoint: /mgmt/cm/device/licensing/pool/regkey/licenses/{id}/offerings

Requests

GET /mgmt/cm/device/licensing/pool/regkey/licenses/{id}/offerings

Request Parameters

None

Query Parameters

None

Response

The JSON in the body of a GET response can contain the following parameters.

HTTP/1.1 200 OK

Name Type Description
description string Description of the RegKey pool.
dossier string For manual activation, this provides a dossier you can use to retrieve the license text from the F5 licensing web portal.
encryptedPrivateKey string A value for internal use.
eulaText string The text of the end user license agreement (EULA).
id string Identifier of the RegKey pool.
internalPrivateKey string A value for internal use.
licenseState object Information about the license.
     vendor string The provider of this license.
     licensedDateTime string Formatted Date/Time when licensed. For example, “2017-02-17T00:00:00-08:00”
     licensedVersion string A license version.
message string A description of the activation’s progress. For example, this can be “Automatic activation in progress” or “Accept EULA to continue”.
name string Name of the RegKey pool.
publicKey string A value for internal use.
regKey string The registration key of the license.
selfLink string An url for the collection or specific RegKey pool.
sortName string This value is used by the UI.
status string The current status of the activation. For example “ACTIVATING_AUTOMATIC_NEED_EULA_ACCEPT”

Permissions

Role Allow
device_manager Yes
License_Manager Yes

POST mgmt/cm/device/licensing/pool/regkey/licenses/{id}/offerings

To create a key, you can send a POST request to the collection.

Request Parameters

Name Type Required Description
addOnKeys array Yes A a list of keys for add-on offerings.
description string Yes Description of the RegKey pool.
eulaText string Yes The text of the end user license agreement (EULA).
licenseText string Yes The license text received from the F5 licensing web portal.
regKey string Yes The registration key of the license.
status string Yes The current status of the activation. For example, “ACTIVATING_AUTOMATIC”.

Query Parameters

None

Response

After the POST request completes, you should poll the activation’s status by sending a GET request to the endpoint. The JSON in the response can include the same parameters described for the response to a GET request.

HTTP/1.1 200 OK

Permissions

Role Allow
device_manager Yes
License_Manager Yes

PATCH /mgmt/cm/device/licensing/pool/regkey/licenses/{id}/offerings/{regkey}

To send a PATCH request to the specific offering endpoint to complete activation. You can send a PATCH to retry or reactivate an activation.

Request Parameters

Name Type Required Description
addOnKeys array Yes A a list of keys for add-on offerings.
eulaText string Yes The text of the end user license agreement (EULA).
licenseText string Yes The license text received from the F5 licensing web portal.
status string Yes The current status of the activation. For example, “ACTIVATING_AUTOMATIC_EULA_ACCEPTED” or “ACTIVATING_AUTOMATIC”

Query Parameters

None

Response

After the POST request completes, you should poll the license status by sending a GET request to the endpoint. The JSON in the GET’s response can include the same parameters described for the response to a GET request.

HTTP/1.1 200 OK

Permissions

Role Allow
device_manager Yes
License_Manager Yes

DELETE /mgmt/cm/device/licensing/pool/regkey/licenses/{id}/offerings/{regkey}

Note, you cannot delete a registration key if it is assigned to a BIG-IP device.

Request Parameters

None

Query Parameters

None

Response

The JSON in the body of the response is for the deleted offering.

HTTP/1.1 200 OK

Permissions

Role Allow
device_manager Yes
License_Manager Yes

Examples

GET to find all the keys of a RegKey Pool

You can send a GET request to the offerings collection to list all the existing registration keys for a specified RegKey pool.

GET https://<BIG-IQ>/mgmt/cm/device/licensing/pool/regkey/licenses/{id}/offerings

Response

The response to the GET can look similar to the following example, the items array can contain an item for each existing registration key in the RegKey pool.

{
    "items": [],
    "generation": 0,
    "kind": "cm:device:licensing:pool:regkey:licenses:item:offerings:regkeypoollicenseofferingcollectionstate",
    "lastUpdateMicros": 0,
    "selfLink": "https://<BIG-IQ>/mgmt/cm/device/licensing/pool/regkey/licenses/150102a0-66ec-411f-8776-221019f430f3/offerings"
}

POST to start key activation

To add a new registration key to a RegKey pool and start activation, you can send a POST request to the offerings collection.

POST https://<BIG-IQ>/mgmt/cm/device/licensing/pool/regkey/licenses/{id}/offerings

The body of the POST request can look similar to the following example for starting automatic activation. To start manual activation, set status to “ACTIVATING_MANUAL”. Replace the value of “MY-REGISTRATION-KEY” in this example with your actual BIG-IP VE registration key. You have the option to also include an addOnKeys value in the body for any add-on keys.

{
    "regKey": "MY-REGISTRATION-KEY",
    "status": "ACTIVATING_AUTOMATIC",
    "description": "my freeform description"
}

Response

The JSON in the response can look similar to the following example.

HTTP/1.1 200 OK

{
    "regKey": "MY-REGISTRATION-KEY",
    "sortName": "Registration Key Pool Item",
    "publicKey": [
      16,
      96,
      61,
      ...
    ],
    "internalPrivateKey": "hXIOe4RROD...",
    "encryptedPrivateKey": [
      15,
      104,
      19,
      ...
    ],
    "name": "License for MY-REGISTRATION-KEY",
    "description": "my freeform description",
    "message": "Automatic activation in progress",
    "dossier": "4a133ec092...",
    "status": "ACTIVATING_AUTOMATIC",
    "generation": 1,
    "lastUpdateMicros": 1488538151253316,
    "kind": "cm:device:licensing:pool:regkey:licenses:item:offerings:regkeypoollicenseofferingstate",
    "selfLink": "https://localhost/mgmt/cm/device/licensing/pool/regkey/licenses/150102a0-66ec-411f-8776-221019f430f3/offerings/Q0223-28107-64761-06159-4281213"
}

Note that the body of the response can contain a selfLink, which you can poll to check the activation status of the key.

GET to poll activation status

After starting activation, you can send GET requests to poll for the activation’s status. You should continue polling until the response indicates the activation is ready to continue.

GET https://<BIG-IQ>/mgmt/cm/device/licensing/pool/regkey/licenses/{id}/offerings/{regkey}

Response

When activation is ready to continue, the JSON in the response can look similar to the following example. For an automatic activation, and after BIG-IQ has retrieved the end user license agreement (EULA), the value of status transitions to “ACTIVATING_AUTOMATIC_NEED_EULA_ACCEPT”, which means you must accept the EULA to continue.

{
    "eulaText": "END USER LICENSE AGREEMENT\r\nDOC-0355-08\r\n\r\nIMPORTANT - READ BEFORE..."
    "message": "Accept EULA to continue",
    "status": "ACTIVATING_AUTOMATIC_NEED_EULA_ACCEPT",
    ...
}

PATCH to accept the EULA

To continue automatic activation you can send a PATCH request to the endpoint of the specific activation.

PATCH https://<BIG-IQ>/mgmt/cm/device/licensing/pool/regkey/licenses/{id}/offerings/{regkey}

To accept the EULA and continue automatic activation, the JSON in the PATCH request can look similar to the following example.

{
    "status": "ACTIVATING_AUTOMATIC_EULA_ACCEPTED",
    "eulaText": "END USER LICENSE AGREEMENT\r\nDOC-0355-08\r\n\r\nIMPORTANT - READ BEFORE..."
}

Response

The initial response to the PATCH request can indicate that the activation is continuing.

HTTP/1.1 200 OK

{
    "message": "Finishing activation",
    "status": "ACTIVATING_AUTOMATIC_EULA_ACCEPTED",
    ...
}

Again poll for the status of the activation by sending a GET request to the specific activation. The activation process has completed when the value of status transitions to “READY” or “ACTIVATION_FAILED”.

PATCH to provide license text and continue manual activation

To continue manual activation you can send a PATCH request to the specific activation.

PATCH https://<BIG-IQ>/mgmt/cm/device/licensing/pool/regkey/licenses/{id}/offerings/{regkey}

For manual activation, the PATCH request can provide the license text received from the F5 licensing web portal. The JSON in the body of the PATCH request can look similar to the following example.

{
    "status": "ACTIVATING_MANUAL_LICENSE_TEXT_PROVIDED",
    "licenseText": "..."
}

Response

The initial response to the PATCH request can indicate the activation is continuing.

HTTP/1.1 200 OK

{
    "licenseState": {
      "vendor": "F5 Networks, Inc.",
      "licensedDateTime": "2017-03-03T00:00:00-08:00",
      "licensedVersion": "5.2.0",
      ...
    },
    "message": "Activated",
    "status": "READY",
    ...
}

You can poll for the status of the activation by sending a GET request to the specific offering. The activation process has completed when the value of status in the response has transitioned to “READY” or “ACTIVATION_FAILED”.

PATCH to retry a failed activation

If an activation fails, check the error messages returned from the API and the restjavad logs. To retry, correct the errors and send a PATCH request to the specific offering.

PATCH https://<BIG-IQ>/mgmt/cm/device/licensing/pool/regkey/licenses/{id}/offerings/{regkey}

To retry automatic activation, the value of status can be “ACTIVATING_AUTOMATIC”. To retry manual activation, the value of status can be “ACTIVATING_MANUAL”. For example, the JSON in the body of a PATCH request for automatic activation can look similar to the following example.

{
    "status": "ACTIVATING_AUTOMATIC"
}

Response

The initial response to the PATCH request can indicate that the activation is continuing.

HTTP/1.1 200 OK

{
    "message": "Automatic activation in progress",
    "status": "ACTIVATING_AUTOMATIC",
    ...
}

You can poll for the status of the activation by sending a GET request to the specific activation endpoint. The activation process has completed when the value of status transitions to “READY” or “ACTIVATION_FAILED”.

PATCH to reactivate a license with add-on keys

After a registration key is activated, you can reactivate it by sending a PATCH request to the key endpoint. For example, you can need to reactivate a license after adding an add-on key.

PATCH https://<BIG-IQ>/mgmt/cm/device/licensing/pool/regkey/licenses/{id}/offerings/{regkey}

The body of the PATCH request can look similar to the following. Replace “MY-ADD-ON-KEY” in this example with your actual add-on key.

{
    "status": "ACTIVATING_AUTOMATIC",
    "addOnKeys": ["MY-ADD-ON-KEY"]
}

Response

After the PATCH completes, you can send GET requests to poll the activation status.

HTTP/1.1 200 OK

{
    "message": "Automatic activation in progress",
    "status": "ACTIVATING_AUTOMATIC",
    ...
}

DELETE to remove a registration key

To remove a registration key from a RegKey pool, you can send a DELETE request to the key endpoint.

Note, you cannot delete a registration key if it has been assigned to a BIG-IP device.

DELETE https://<BIG-IQ>/mgmt/cm/device/licensing/pool/regkey/licenses/{id}/offerings/{regkey}

Response

The JSON in the body of the response is for the deleted offering.

HTTP/1.1 200 OK