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, 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

Previous Next