License API

Related pages:

This page describes the License APIs you can use to perform functions related to licensing and accounts including uploading license files, allocating licenses, getting license and account usage information as well as creating, updating, and deleting license rules.

The License APIs below are separated by licensing model. To learn about licenses within each model, see License Entitlements and Restrictions.

APIs for Infrastructure-based Licensing:

Account Usage API

A RESTful API to programmatically retrieve account usage by license and account ID.

Retrieve Account Usage by License ID

Retrieve account usage referenced by given license ID.

URL

http://<host>:<port>/controller/licensing/v1/usage/license/{licenseId}

Format

GET /controller/licensing/v1/usage/license/{licenseId}

Path Parameters

Parameter Name	Parameter Type	Value	Mandatory
`licenseId`	String	License Id for which an usage is requested to be retrieved.	Yes

Query Parameters

Parameter Name	Parameter Type	Value	Mandatory
`dateFrom`	String	Start date of requested license usage period. Expected format is ISO-8601 (extended). For example: '2020-10-05T10:00:00Z'.	Yes
`dateTo`	String	End date of requested license usage period. Expected format is ISO-8601 (extended). For example: '2020-10-05T10:00:00Z'.	Yes
`granularityMinutes`	Integer	Requested granularity of the license usage data.	Yes
`includeEntityTypes`	Boolean	Determines whether to include licensed entity type usage or not. The default is `false.`	No
`includeConsumptionBased`	Boolean	Whether to include consumption-based usages. he default is `false.`	No

Response Format

response Object

Parameter Name	Parameter Type	Value
`accountId`	Integer	Account ID.
`licenseRule`	Object	Entity representing license usage either for an account or for an allocation.
`packages`	Array of package Objects

licenseRule Object

Parameter Name	Parameter Type	Value
`id`	String	Allocation ID.
`name`	String	Allocation name.
`licenseKey`	String	License key for this particular allocation.

packageObject

Parameter Name	Parameter Type	Value
`packageName`	String	An enumeration representing the name of the package (edition) instance: "INFRA" "PREMIUM" "ENTERPRISE"
`type`	String	An enumeration representing the type of the package instance: "PAID" "TRIAL" "LITE"
`kind`	String	Package kind derived from the licensing model where the package originated from. Useful for quickly distinguishing packages based on the legacy Agent based license modules (APM, DOTNET, etc.) from the new Infrastructure based packages. Enum: "AGENT_BASED" "INFRASTRUCTURE_BASED"
`family`	String	Package family.
`createdDate`	String	Creation date of the package instance in the license. ISO 8601 date-time string.
`startDate`	String	Start date of the package instance. For example, the date from which the package instance becomes active: ISO 8601 date-time string.
`expirationDate`	String	Expiration date of the package instance, i.e. date from which the package instance is no longer active. ISO 8601 date-time string.
`licenseUnits`	String	Number of licenses available for the package instance.
`properties`	Object	Collection of package specific custom properties in the form of key-value pairs. In case of merging with global properties, conflicting package specific properties take precedence.

Example

curl --user <user>@<AccountName>:<password> -X GET \
  http://<host>:<port>/controller/licensing/v1/usage/license/{licenseId}?dateFrom=<ISO 8601 date-time string>&dateTo=<ISO 8601 date-time string>&granularityMinutes=<number of minutes as an integer>

{
    "accountId":0,
    "licenseRule":{
        "id":"string",
        "name":"string",
        "licenseKey":"string"
    },
    "packages":[
        {
            "name":"string",
            "unitUsages":[
                {
                    "usageType":"string",
                    "granularityInMinutes":0,
                    "data":{
                        "timestamp":"string",
                        "provisioned":{
                            "min":0,
                            "max":0,
                            "avg":0,
                            "count":0
                        },
                        "used":{
                            "min":0,
                            "max":0,
                            "avg":0,
                            "count":0
                        },
                        "registrations":[
                            {
                                "type":"string",
                                "registered":{
                                    "min":0,
                                    "max":0,
                                    "avg":0,
                                    "count":0
                                }
                            }
                        ]
                    }
                }
            ]
        }
    ]
}

Retrieve Account Usage by Account ID

Retrieve account usage referenced by given account ID.

URL

http://<host>:<port>/controller/licensing/v1/usage/account/{accountId}

Format

GET /controller/licensing/v1/usage/account/{accountId}

Path Parameters

Parameter Name	Parameter Type	Value	Mandatory
`accountId`	Integer	Account ID for which a usage is requested to be retrieved.	Yes

Query Parameters

Parameter Name	Parameter Type	Value	Mandatory
`dateFrom`	String	Start date of requested license usage period. Expected format is ISO-8601 (extended). For example: '2020-10-05T10:00:00Z'.	Yes
`dateTo`	String	End date of requested license usage period. Expected format is ISO-8601 (extended). For example: '2020-10-05T10:00:00Z'.	Yes
`granularityMinutes`	Integer	Requested granularity of the license usage data.	Yes
`includeEntityTypes`	Boolean	Determines whether to include licensed entity type usage or not. The default is `false.`	No
`includeConsumptionBased`	Boolean	Whether to include consumption-based usages. he default is `false.`	No

Response Format

response Object

Parameter Name	Parameter Type	Value
`accountId`	Integer	Account ID.
`licenseRule`	Object	Entity representing license usage either for an account or for an allocation.
`packages`	Array	Package objects

licenseRule Object

Parameter Name	Parameter Type	Value
`id`	String	Allocation ID.
`name`	String	Allocation name.
`licenseKey`	String	License key for this particular allocation.

packageObject

Parameter Name	Parameter Type	Value
`packageName`	String	An enumeration representing the name of the package (edition) instance: "INFRA" "PREMIUM" "ENTERPRISE"
`type`	String	An enumeration representing the type of the package instance: "PAID" "TRIAL" "LITE"
`kind`	String	Package kind derived from the licensing model where the package originated from. Useful for quickly distinguishing packages based on the legacy Agent based license modules (APM, DOTNET, etc.) from the new Infrastructure based packages. Enum: "AGENT_BASED" "INFRASTRUCTURE_BASED"
`family`	String	Package family.
`createdDate`	String	Creation date of the package instance in the license. ISO 8601 date-time string.
`startDate`	String	Start date of the package instance. For example, the date from which the package instance becomes active: ISO 8601 date-time string.
`expirationDate`	String	Expiration date of the package instance, i.e. date from which the package instance is no longer active. ISO 8601 date-time string.
`licenseUnits`	String	Number of licenses available for the package instance.
`properties`	Object	Collection of package specific custom properties in the form of key-value pairs. In case of merging with global properties, conflicting package specific properties take precedence.

Example

curl --user <user>@<AccountName>:<password> -X GET \
http://<host>:<port>/controller/licensing/v1/usage/account/{accountId}?dateFrom=<ISO 8601 date-time string>&dateTo=<ISO 8601 date-time string>&granularityMinutes=<number of minutes as an integer>

{
    "accountId":0,
    "licenseRule":{
        "id":"string",
        "name":"string",
        "licenseKey":"string"
    },
    "packages":[
        {
            "name":"string",
            "unitUsages":[
                {
                    "usageType":"string",
                    "granularityInMinutes":0,
                    "data":{
                        "timestamp":"string",
                        "provisioned":{
                            "min":0,
                            "max":0,
                            "avg":0,
                            "count":0
                        },
                        "used":{
                            "min":0,
                            "max":0,
                            "avg":0,
                            "count":0
                        },
                        "registrations":[
                            {
                                "type":"string",
                                "registered":{
                                    "min":0,
                                    "max":0,
                                    "avg":0,
                                    "count":0
                                }
                            }
                        ]
                    }
                }
            ]
        }
    ]
}

License Allocation API

The methods below allow you retrieve, create, filter, and delete license allocations (license rules) for an account.

Retrieve All License Allocations

Retrieve all license allocations, and narrow the list of allocations by using optional query parameters.

URL

http://<host>:<port>/controller/licensing/v1/account/{accountId}/allocation

Format

GET /controller/licensing/v1/account/{accountId}/allocation

Path Parameters

Parameter Name	Parameter Type	Value	Mandatory
`accountId`	Integer	Account identification for which allocations are requested to be retrieved.	Yes

Query Parameters

Parameter Name	Parameter Type	Value	Mandatory
`name`	String	Name of the allocation. Cannot be used in combination with `license-key` and `tag`.	No
`license-key`	String	License key of the allocation. Cannot be used in combination with `name` and `tag`.	No
`tag`	String	Tag associated with allocations. Cannot be used in combination with `name` and `license-key`.	No

Response Format

response Object

Parameter Name	Parameter Type	Value
`id`	String	Allocation ID. Unique per account.
`accountId`	Integer	Account ID the allocation belongs to.
`name`	String	Name of the allocation. Unique per account.
`licenseKey`	String	License key used by the allocation. Unique per account.
`filters`	Array of Objects	Array of filter objects
`limits`	Array of Objects	Array of `limit` objects
`tags`	Array of Strings	Tags associated with the allocation.
`createdDate`	String	Creation date of the allocation: ISO 8601 date-time string.
`lastUpdatedDate`	String	Last update date of the allocation: ISO 8601 date-time string.

filter Object

Parameter Name	Parameter Type	Value
`id`	String	Name of the allocation. Unique per account.
`type`	String	Type of entity on which the filter should be applied. Enum: "APPLICATION" "HOST"
`operator`	String	Operator of the following enumerations used to check the `type` against the `value:` `ID_EQUALS` – Exact match of entity Id `EQUALS` – Exact match of entity value `STARTS_WITH` – Match of entity starting with a value `ENDS_WITH` – Match of entity ending with a value `CONTAINS` – Match of entity containing a value `REGEX` – Match of entity against a regexp
`value`	String	Value to be used to filter against.

limit Object

Parameter Name	Parameter Type	Value
`id`	String	Allocation package limit ID.
`package`	String	Type of package for the limit. The following are the supported enumerations: "INFRA" "PREMIUM" "ENTERPRISE"
`units`	Integer	Number of license units per the allocation limit.
`tags`	Array of Strings	Tags associated with the allocation.

Example

curl --user <user>@<AccountName>:<password> -X GET \
http://<host>:<port>/controller/licensing/v1/account/{accountId}/allocation

[
    {
        "id":"string",
        "accountId":0,
        "name":"string",
        "licenseKey":"string",
        "filters":[
            {
                "id":"string",
                "type":"APPLICATION",
                "operator":"ID_EQUALS",
                "value":"string"
            }
        ],
        "limits":[
            {
                "id":"string",
                "package":"INFRA",
                "units":0
            }
        ],
        "tags":[
            "string"
        ],
        "createdDate":"string",
        "lastUpdatedDate":"string"
    }
]

YML

Retrieve Allocation Usage by Account ID

Retrieve allocation rule usage referenced by a given license key ID.

URL

http://<host>:<port>/controller/licensing/v1/usage/account/{accountId}/allocation/{licenseKey}

Format

GET /controller/licensing/v1/usage/account/{accountId}/allocation/{licenseKey}

Path Parameters

Parameter Name	Parameter Type	Value	Mandatory
`accountId`	Integer	Account ID for which a usage is requested to be retrieved.	Yes
`licenseKey`	String	License key based on the allocation rule is selected. Returned usage will be related to that particular allocation rule.	Yes

Query Parameters

Parameter Name	Parameter Type	Value	Mandatory
`dateFrom`	String	Start date of requested license usage period. Expected format is ISO-8601 (extended). For example: '2020-10-05T10:00:00Z'.	Yes
`dateTo`	String	End date of requested license usage period. Expected format is ISO-8601 (extended). For example: '2020-10-05T10:00:00Z'.	Yes
`granularityMinutes`	Integer	Requested granularity of the license usage data.	Yes
`includeEntityTypes`	Boolean	Determines whether to include licensed entity type usage or not. The default is `false.`	No

Response Format

response Object

Parameter Name	Parameter Type	Value
`accountId`	Integer	Account ID.
`licenseRule`	Object	Entity representing license usage either for an account or for an allocation.
`packages`	Array	Package objects.

licenseRule Object

Parameter Name	Parameter Type	Value
`id`	String	Allocation ID.
`name`	String	Allocation name.
`licenseKey`	String	License key for this particular allocation.

packageObject

Parameter Name	Parameter Type	Value
Parameter Name	Parameter Type	Value
`packageName`	String	An enumeration representing the name of the package (edition) instance: "INFRA" "PREMIUM" "ENTERPRISE"
`type`	String	An enumeration representing the type of the package instance: "PAID" "TRIAL" "LITE"
`kind`	String	Package kind derived from the licensing model where the package originated from. Useful for quickly distinguishing packages based on the legacy Agent based license modules (APM, DOTNET, etc.) from the new Infrastructure based packages. Enum: "AGENT_BASED" "INFRASTRUCTURE_BASED"
`family`	String	Package family.
`createdDate`	String	Creation date of the package instance in the license. ISO 8601 date-time string.
`startDate`	String	Start date of the package instance. For example, the date from which the package instance becomes active: ISO 8601 date-time string.
`expirationDate`	String	Expiration date of the package instance, i.e. date from which the package instance is no longer active. ISO 8601 date-time string.
`licenseUnits`	String	Number of licenses available for the package instance.
`properties`	Object	Collection of package specific custom properties in the form of key-value pairs. In case of merging with global properties, conflicting package specific properties take precedence.

Example

curl --user <user>@<AccountName>:<password> -X GET \
http://<host>:<port>/controller/licensing/v1/usage/account/{accountId}/allocation/{licenseKey}?dateFrom=<ISO 8601 date-time string>&dateTo=<ISO 8601 date-time string>&granularityMinutes=<number of minutes as an integer>

{
    "accountId":0,
    "licenseRule":{
        "id":"string",
        "name":"string",
        "licenseKey":"string"
    },
    "packages":[
        {
            "name":"string",
            "unitUsages":[
                {
                    "usageType":"string",
                    "granularityInMinutes":0,
                    "data":{
                        "timestamp":"string",
                        "provisioned":{
                            "min":0,
                            "max":0,
                            "avg":0,
                            "count":0
                        },
                        "used":{
                            "min":0,
                            "max":0,
                            "avg":0,
                            "count":0
                        },
                        "registrations":[
                            {
                                "type":"string",
                                "registered":{
                                    "min":0,
                                    "max":0,
                                    "avg":0,
                                    "count":0
                                }
                            }
                        ]
                    }
                }
            ]
        }
    ]
}

Retrieve Allocation Usage by License Key

Retrieve allocation usage referenced by a given license key.

URL

http://<host>:<port>/controller/licensing/v1/usage/license/{licenseId}/allocation/{licenseKey}

Format

GET /controller/licensing/v1/usage/license/{licenseId}/allocation/{licenseKey}

Path Parameters

Parameter Name	Parameter Type	Value	Mandatory
`licenseId`	String	License ID for which a usage is requested to be retrieved.	Yes
`licenseKey`	String	License key based on the allocation rule is selected. Returned usage will be related to that particular allocation rule.	Yes

Query Parameters

Parameter Name	Parameter Type	Value	Mandatory
`dateFrom`	String	Start date of requested license usage period. Expected format is ISO-8601 (extended). For example: '2020-10-05T10:00:00Z'.	Yes
`dateTo`	String	End date of requested license usage period. Expected format is ISO-8601 (extended). For example: '2020-10-05T10:00:00Z'.	Yes
`granularityMinutes`	Integer	Requested granularity of the license usage data.	Yes
`includeEntityTypes`	Boolean	Determines whether to include licensed entity type usage or not. The default is `false.`	No

Response Format

response Object

Parameter Name	Parameter Type	Value
`accountId`	Integer	Account ID.
`licenseRule`	Object	Entity representing license usage either for an account or for an allocation.
`packages`	Array of package objects	Package objects.

licenseRule Object

Parameter Name	Parameter Type	Value
`id`	String	Allocation ID.
`name`	String	Allocation name.
`licenseKey`	String	License key for this particular allocation.

packageObject

Parameter Name	Parameter Type	Value
Parameter Name	Parameter Type	Value
`packageName`	String	An enumeration representing the name of the package (edition) instance: "INFRA" "PREMIUM" "ENTERPRISE"
`type`	String	An enumeration representing the type of the package instance: "PAID" "TRIAL" "LITE"
`kind`	String	Package kind derived from the licensing model where the package originated from. Useful for quickly distinguishing packages based on the legacy Agent based license modules (APM, DOTNET, etc.) from the new Infrastructure based packages. Enum: "AGENT_BASED" "INFRASTRUCTURE_BASED"
`family`	String	Package family.
`createdDate`	String	Creation date of the package instance in the license. ISO 8601 date-time string.
`startDate`	String	Start date of the package instance. For example, the date from which the package instance becomes active: ISO 8601 date-time string.
`expirationDate`	String	Expiration date of the package instance, i.e. date from which the package instance is no longer active. ISO 8601 date-time string.
`licenseUnits`	String	Number of licenses available for the package instance.
`properties`	Object	Collection of package specific custom properties in the form of key-value pairs. In case of merging with global properties, conflicting package specific properties take precedence.

Example

curl --user <user>@<AccountName>:<password> -X GET \
http://<host>:<port>/controller/licensing/v1/usage/license/{licenseId}/allocation/{licenseKey}?dateFrom=<ISO 8601 date-time string>&dateTo=<ISO 8601 date-time string>&granularityMinutes=<number of minutes as an integer>

{
    "accountId":0,
    "licenseRule":{
        "id":"string",
        "name":"string",
        "licenseKey":"string"
    },
    "packages":[
        {
            "name":"string",
            "unitUsages":[
                {
                    "usageType":"string",
                    "granularityInMinutes":0,
                    "data":{
                        "timestamp":"string",
                        "provisioned":{
                            "min":0,
                            "max":0,
                            "avg":0,
                            "count":0
                        },
                        "used":{
                            "min":0,
                            "max":0,
                            "avg":0,
                            "count":0
                        },
                        "registrations":[
                            {
                                "type":"string",
                                "registered":{
                                    "min":0,
                                    "max":0,
                                    "avg":0,
                                    "count":0
                                }
                            }
                        ]
                    }
                }
            ]
        }
    ]
}

Create a License Allocation

Create a license allocation. For this method, make sure:

IDs of sub-entities (filters, limits) are not filled
Other unique parameters (e.g., name, licenseKey) don't conflict with existing allocations

URL

http://<host>:<port>/controller/licensing/v1/account/{accountId}/allocation

Format

POST /controller/licensing/v1/account/{accountId}/allocation

Path Parameters

Parameter Name	Parameter Type	Value	Mandatory
`accountId`	Integer	Account identification for which allocations are requested to be retrieved.	Yes

Request Format

request Object

Parameter Name	Parameter Type	Value
`name`	String	Name of the allocation. Unique per account.
`filters`	Array of Objects	Array of `filter` objects
`limits`	Array of Objects	Array of `limit` objects

Filter Object

Parameter Name	Parameter Type	Value
`id`	String	Name of the allocation. Unique per account.
`type`	String	Type of entity on which the filter should be applied. Enum: "APPLICATION" "HOST"
`operator`	String	Operator of the following enumerations used to check the `type` against the `value:` `ID_EQUALS` – Exact match of entity Id `EQUALS` – Exact match of entity value `STARTS_WITH` – Match of entity starting with a value `ENDS_WITH` – Match of entity ending with a value `CONTAINS` – Match of entity containing a value `REGEX` – Match of entity against a regexp
`value`	String	Value to be used to filter against.

limit Object

Parameter Name	Parameter Type	Value
`id`	String	Allocation package limit ID.
`package`	String	Type of package for the limit. The following are the supported enumerations: "INFRA" "PREMIUM" "ENTERPRISE"
`units`	Integer	Number of license units per the allocation limit.
`tags`	Array of Strings	Tags associated with the allocation.

Response Format

response Object

Parameter Name	Parameter Type	Value
`id`	String	Allocation ID. Unique per account.
`accountId`	Integer	Account ID the allocation belongs to.
`name`	String	Name of the allocation. Unique per account.
`licenseKey`	String	License key used by the allocation. Unique per account.
filters	Array of Objects	Array of filter objects
`limits`	Array of Objects	Array of `limit` objects
`tags`	Array of Strings	Tags associated with the allocation.
`createdDate`	String	Creation date of the allocation: ISO 8601 date-time string.
`lastUpdatedDate`	String	Last update date of the allocation: ISO 8601 date-time string.

filter Object

Parameter Name	Parameter Type	Value
`id`	String	Name of the allocation. Unique per account.
`type`	String	Type of entity on which the filter should be applied. Enum: "APPLICATION" "HOST"
`operator`	String	Operator of the following enumerations used to check the `type` against the `value:` `ID_EQUALS` – Exact match of entity Id `EQUALS` – Exact match of entity value `STARTS_WITH` – Match of entity starting with a value `ENDS_WITH` – Match of entity ending with a value `CONTAINS` – Match of entity containing a value `REGEX` – Match of entity against a regexp
`value`	String	Value to be used to filter against.

limit Object

Parameter Name	Parameter Type	Value
`id`	String	Allocation package limit ID.
`package`	String	Type of package for the limit. The following are the supported enumerations: "INFRA" "PREMIUM" "ENTERPRISE"
`units`	Integer	Number of license units per the allocation limit.
`tags`	Array of Strings	Tags associated with the allocation.

Example

curl --user <user>@<AccountName>:<password> -X POST \
http://<host>:<port>/controller/licensing/v1/account/{accountId}/allocation \
-H 'Content-Type: application/json' \
-d '{
        "name": "string", 
        "filters": [
            {
                "id": "string",
                 "type": "APPLICATION",
                 "operator": "ID_EQUALS",
                 "value": "string"
            }
        ],
        "limits": [
            {
                "id": "string",
                "package": "INFRA",
                "units": 0
            }
        ],
        "tags": ["string"]
    }'

[
    {
        "id": "string",        
        "accountId": integer,   
        "name": "string",       
        "licenseKey": "string", 
        "filters": [
            {
                "id": "string",
                 "type": "APPLICATION",
                 "operator": "ID_EQUALS",
                 "value": "string"
            }
        ],
        "limits": [
            {
                "id": "string",
                "package": "INFRA",
                "units": 0
            }
        ],
        "tags": ["string"],
        "createdDate": "ISO 8601 date-time",
        "lastUpdatedDate": "ISO 8601 date-time"
    },
    ...
]

YML

Retrieve a License Allocation

Retrieve a license allocation by allocation ID.

URL

http://<host>:<port>/controller/licensing/v1/account/{accountId}/allocation/{allocationId}

Format

GET /controller/licensing/v1/account/{accountId}/allocation/{allocationId}

Path Parameters

Parameter Name	Parameter Type	Value	Mandatory
`accountId`	Integer	Account identification for which allocations are requested to be retrieved.	Yes
`allocationId`	String	Allocation ID referencing allocation to be retrieved.	Yes

Response Format

response Object

Parameter Name	Parameter Type	Value
`id`	String	Allocation ID. Unique per account.
`accountId`	Integer	Account ID the allocation belongs to.
`name`	String	Name of the allocation. Unique per account.
`licenseKey`	String	License key used by the allocation. Unique per account.
`filters`	Array of Objects	Array of filter objects
`limits`	Array of Objects	Array of `limit` objects
`tags`	Array of Strings	Tags associated with the allocation.
`createdDate`	String	Creation date of the allocation: ISO 8601 date-time string.
`lastUpdatedDate`	String	Last update date of the allocation: ISO 8601 date-time string.

filter Object

Parameter Name	Parameter Type	Value
`id`	String	Name of the allocation. Unique per account.
`type`	String	Type of entity on which the filter should be applied. Enum: "APPLICATION" "HOST"
`operator`	String	Operator of the following enumerations used to check the `type` against the `value:` `ID_EQUALS` – Exact match of entity Id `EQUALS` – Exact match of entity value `STARTS_WITH` – Match of entity starting with a value `ENDS_WITH` – Match of entity ending with a value `CONTAINS` – Match of entity containing a value `REGEX` – Match of entity against a regexp
`value`	String	Value to be used to filter against.

limit Object

Parameter Name	Parameter Type	Value
`id`	String	Allocation package limit ID.
`package`	String	Type of package for the limit. The following are the supported enumerations: "INFRA" "PREMIUM" "ENTERPRISE"
`units`	Integer	Number of license units per the allocation limit.
`tags`	Array of Strings	Tags associated with the allocation.

Example

curl --user <user>@<AccountName>:<password> -X GET \
http://<host>:<port>/controller/licensing/v1/account/{accountId}/allocation/{allocationId}

[
    {
        "id": "string",        
        "accountId": integer,   
        "name": "string",       
        "licenseKey": "string", 
        "filters": [
            {
                "id": "string",
                 "type": "APPLICATION",
                 "operator": "ID_EQUALS",
                 "value": "string"
            }
        ],
        "limits": [
            {
                "id": "string",
                "package": "INFRA",
                "units": 0
            }
        ],
        "tags": ["string"],
        "createdDate": "ISO 8601 date-time",
        "lastUpdatedDate": "ISO 8601 date-time"
    },
    ...
]

YML

Update a License Allocation

Update a license allocation by allocation ID.

URL

http://<host>:<port>/controller/licensing/v1/account/{accountId}/allocation/{allocationId}

Format

PUT /controller/licensing/v1/account/{accountId}/allocation/{allocationId}

Path Parameters

Parameter Name	Parameter Type	Value	Mandatory
`accountId`	Integer	Account identification for which allocations are requested to be retrieved.	Yes
`allocationId`	String	Allocation ID referencing allocation to be retrieved.	Yes

Request Format

request Object

Parameter Name	Parameter Type	Value	Mandatory
`name`	String	Name of the allocation. Unique per account.	Yes
`filters`	String	Allocation ID referencing allocation to be retrieved.	No
`limits`	Object		No
`tags`	Array of Strings		No

filter Object

Parameter Name	Parameter Type	Value
`id`	String	Name of the allocation. Unique per account.
`type`	String	Type of entity on which the filter should be applied. Enum: "APPLICATION" "HOST"
`operator`	String	Operator of the following enumerations used to check the `type` against the `value:` `ID_EQUALS` – Exact match of entity Id `EQUALS` – Exact match of entity value `STARTS_WITH` – Match of entity starting with a value `ENDS_WITH` – Match of entity ending with a value `CONTAINS` – Match of entity containing a value `REGEX` – Match of entity against a regexp
`value`	String	Value to be used to filter against.

limit Object

Parameter Name	Parameter Type	Value
`id`	String	Allocation package limit ID.
`package`	String	Type of package for the limit. The following are the supported enumerations: "INFRA" "PREMIUM" "ENTERPRISE"
`units`	Integer	Number of license units per the allocation limit.
`tags`	Array of Strings	Tags associated with the allocation.

Example

curl --user <user>@<AccountName>:<password> -X PUT \
http://<host>:<port>/controller/licensing/v1/account/{accountId}/allocation \
-H 'Content-Type: application/json' \
-d '{
        "name": "string",
        "filters": [
            {
                "id": "string",
                "type": "APPLICATION",
                "operator": "ID_EQUALS",
                "value": "string"
             }
        ],
        "limits": [
            {
                "id": "string",
                "package": "INFRA",
                "units": 0
            }
        ],
        "tags": [
            "string"
        ]
    }'

{
    "id":"string",
    "accountId":0,
    "name":"string",
    "licenseKey":"string",
    "filters":[
        {
            "id":"string",
            "type":"APPLICATION",
            "operator":"ID_EQUALS",
            "value":"string"
        }
    ],
    "limits":[
        {
            "id":"string",
            "package":"INFRA",
            "units":0
        }
    ],
    "tags":[
        "string"
    ],
    "createdDate":"string",
    "lastUpdatedDate":"string"
}

YML

Delete a License Rule Allocation

Delete a license allocation by allocation ID.

URL

http://<host>:<port>/controller/licensing/v1/account/{accountId}/allocation/{allocationId}

Format

DELETE /controller/licensing/v1/account/{accountId}/allocation/{allocationId}

Path Parameters

Parameter Name	Parameter Type	Value	Mandatory
`accountId`	Integer	Account identification for which allocations are requested to be retrieved.	Yes
`allocationId`	String	Allocation ID referencing allocation to be retrieved.	Yes

Example

curl --user <user>@<AccountName>:<password> -X DELETE \
http://<host>:<port>/controller/licensing/v1/account/{accountId}/allocation/{allocationId}

License Info API

A RESTful API to programmatically retrieve license information for an account, such as license type, package, and expiration date.

Retrieve Account License Information

Retrieve license information for an account.

URL

http://<host>:<port>/controller/licensing/v1/account/{accountId}/info

Format

GET /controller/licensing/v1/account/{accountId}/info

Path Parameters

Parameter Name	Parameter Type	Value	Mandatory
`accountId`	Integer	Account identification for which allocations are requested to be retrieved.	Yes

Response Format

response Object

Parameter Name	Parameter Type	Value
`accountId`	Integer	Account ID the license info belongs to.
`licenseId`	String	SFDC license ID.
`customerId`	String	Customer ID.
`customerName`	String	Customer name.
`environment`	String	Enumerations representing the environment the license is intended to be used on: "DEV/TEST" PROD"
`hardwareFingerprint`	String	Hardware fingerprint of a machine the license is intended to be used on. Currently only the MAC address is supported. Might be `ANY` for no restrictions.
`type`	String	Enumeration representing the intended consumer of the license: "SAAS-CONTROLLER" "SAAS-ACCOUNT" "ONPREM-CONTROLLER" "ONPREM-ACCOUNT"
`expirationDate`	String	Expiration date of the whole license: ISO 8601 date-time string.
`status`	String	Enumeration representing the license status: "ACTIVE" - Unexpired and paID license. All units are paid. "LIMITED" - Unexpired and either lite or trial. at least one unit is LITE or TRIAL. "EXPIRED" - Expired license.
`packages`	Array of Objects
`properties`	Object	Collection of global custom properties tied to the license in the form of key → value. These properties might be shared among all packages.
`fallbackUnits`	Object	Account level fallback unit definition, it is mapping agent types (string) to their fallback units (integer).

package Object

Parameter Name	Parameter Type	Value
`packageName`	String	An enumeration representing the name of the package (edition) instance: "INFRA" "PREMIUM" "ENTERPRISE"
`type`	String	An enumeration representing the type of the package instance: "PAID" "TRIAL" "LITE"
`kind`	String	Package kind derived from the licensing model where the package originated from. Useful for quickly distinguishing packages based on the legacy Agent based license modules (APM, DOTNET, etc.) from the new Infrastructure based packages. Enum: "INFRASTRUCTURE_BASED"
`family`	String	Package family.
`createdDate`	String	Creation date of the package instance in the license. ISO 8601 date-time string.
`startDate`	String	Start date of the package instance. For example, the date from which the package instance becomes active: ISO 8601 date-time string.
`expirationDate`	String	Expiration date of the package instance, i.e. date from which the package instance is no longer active. ISO 8601 date-time string.
`licenseUnits`	String	Number of licenses available for the package instance.
`properties`	Object	Collection of package specific custom properties in the form of key-value pairs. In case of merging with global properties, conflicting package specific properties take precedence.

Example

curl --user <user>@<AccountName>:<password> -X GET \
http://<host>:<port>/controller/licensing/v1/account/{accountId}/info

{
    "accountId":0,
    "licenseId":"string",
    "customerId":"string",
    "customerName":"string",
    "environment":"DEV/TEST",
    "hardwareFingerprint":"string",
    "type":"SAAS-CONTROLLER",
    "expirationDate":"string",
    "status":"ACTIVE",
    "packages":[
        {
            "packageName":"INFRA",
            "type":"PAID",
            "kind":"AGENT_BASED",
            "family":"string",
            "createdDate":"string",
            "startDate":"string",
            "expirationDate":"string",
            "licenseUnits":0,
            "properties":{
                
            }
        }
    ],
    "properties":{
        
    },
    "fallbackUnits":{
        
    }
}

YML

APIs for Agent-based Licensing:

License Rules API

This section describes the License Rules API methods you can use to retrieve information about the license rules as modeled in AppDynamics such as creating, updating and deleting license rules, and also retrieving license rules by its ID, access key, and name.

The following are true for all License Rule APIs:

id—is GUID (or UUID) which is an acronym for Globally Unique Identifier.
access_key—must be unique across all licenseRules.
name—must be unique across all licenseRules.
account_id—Use GET API to know your current account_ID.

Creates a New License Rule

URL

http://<host>:<port>/controller/mds/v1/license/rules

Format

POST /controller/mds/v1/license/rules

Input Parameters

Parameter Name	Parameter Type	Value	Mandatory
`license_module_type`	String	String representing the type of the license module. Module types are: NETVIZ MACHINE_AGENT SIM_MACHINE_AGENT APM APP_AGENT DOT_NET_AGENT	Yes
`id`	String	String representing the ID or name.	Yes
`version`	Integer	Indicates the version number.	Yes
`number_of_licenses`	Integer	Integer indicating the required number of licenses.	Yes
`account_id`	String	Provides the account name or account ID.	Yes
`access_key`	Path	Provides the account access key.	Yes

LicenseRule is comprised of license_module_type, id, access_key, account_id, version, and number_of_licenses.

Example

curl --user <user>@<AccountName>:<password> -X POST \
  http://<host>:<port>/controller/mds/v1/license/rules \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "011116a4-124c-4b73-9343-f315836f103b",
    "version": 0,
    "name": "Default_API9",
    "description": null,
    "enabled": true,
    "constraints": [],
    "entitlements": [
        {
            "license_module_type": "JAVA",
            "number_of_licenses": 100
        },
        {
            "license_module_type": "NATIVE_WEB_SERVER",
            "number_of_licenses": 100
        },
        {
            "license_module_type": "NATIVE_SDK",
            "number_of_licenses": 100
        },
        {
            "license_module_type": "DOT_NET",
            "number_of_licenses": 100
        },
        {
            "license_module_type": "NETVIZ",
            "number_of_licenses": 100
        },
        {
            "license_module_type": "MACHINE_AGENT",
            "number_of_licenses": 100
        },
        {
            "license_module_type": "NODEJS",
            "number_of_licenses": 100
        },
        {
            "license_module_type": "SIM_MACHINE_AGENT",
            "number_of_licenses": 100
        },
        {
            "license_module_type": "PHP",
            "number_of_licenses": 100
        },
        {
            "license_module_type": "PYTHON",
            "number_of_licenses": 100
        }
    ],
    "account_id": "8b1e92f2-387c-45b6-9bb5-ebd7f67587d4",
    "access_key": "ap1845ad-1f3e-4c9b-909b-a3cfa510bfb0",
    "total_licenses": null,
    "peak_usage": null
}

{  
   "id": "011116a4-124c-4b73-9343-f315836f103b",
   "version": 0,
   "name": "Default_API9",
   "description": null,
   "enabled": true,
   "constraints": [  

   ],
   "entitlements": [  
      {  
         "license_module_type": "JAVA",
         "number_of_licenses": 100
      },
      {  
         "license_module_type": "NATIVE_WEB_SERVER",
         "number_of_licenses": 100
      },
      {  
         "license_module_type": "NATIVE_SDK",
         "number_of_licenses": 100
      },
      {  
         "license_module_type": "DOT_NET",
         "number_of_licenses": 100
      },
      {  
         "license_module_type": "NETVIZ",
         "number_of_licenses": 100
      },
      {  
         "license_module_type": "MACHINE_AGENT",
         "number_of_licenses": 100
      },
      {  
         "license_module_type": "NODEJS",
         "number_of_licenses": 100
      },
      {  
         "license_module_type": "SIM_MACHINE_AGENT",
         "number_of_licenses": 100
      },
      {  
         "license_module_type": "PHP",
         "number_of_licenses": 100
      },
      {  
         "license_module_type": "PYTHON",
         "number_of_licenses": 100
      }
   ],
   "account_id": "8b1e92f2-387c-45b6-9bb5-ebd7f67587d4",
   "access_key": "ap1845ad-1f3e-4c9b-909b-a3cfa510bfb0",
   "total_licenses": null,
   "peak_usage": null
}

The version must be 0 when creating.

Returns a Summary of All the License Rules for the Current Account

Use this to retrieve a summary of the license rules. The data transfer objects (DTOs) returned will not contain any constraints, match conditions, or entitlements.

URL

http://<host>:<port>/controller/mds/v1/license/rules

Format

GET /controller/mds/v1/license/rules

Example

[
    {
        "id":"f36e08e2-5f57-4b8c-9ad2-f18873adcd87",
        "version":2,
        "name":"Default",
        "description":null,
        "enabled":true,
        "constraints":[
            
        ],
        "entitlements":[
            
        ],
        "account_id":"0429fc7b-a2b9-42e3-a7fb-f704d436a054",
        "access_key":"account-accesskey-123",
        "total_licenses":120,
        "peak_usage":null
    }
]

Updates a License Rule

URL

http://<host>:<port>/controller/mds/v1/license/rules

Format

PUT /controller/mds/v1/license/rules

Input parameters

Parameter Name	Parameter Type	Value	Mandatory
id	String	String representing the ID or name.	Yes
license_module_type	String	String representing the type of the license module. Module types are: NetViz Machine Agent SIM Machine Agent APM	Yes
version	Integer	Indicates the version number.	Yes
number_of_licenses	Integer	Integer indicating the required number of licenses.	Yes
account_id	String	Provides the account name or account ID.	Yes
access_key	Path	Provides the account access key.	Yes

Example Request

curl -v -X PUT http://<host>:<port>/controller/mds/v1/license/rules \
  --user <user>@<AccountName>:<password> \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "321116a4-124c-4b73-9343-f315836f103b",
    "version": 0,
    "name": "Default_API",
    "description": null,
    "enabled": true,
    "constraints": [],
    "entitlements": [
        {
            "license_module_type": "JAVA",
            "number_of_licenses": 1000
        },
        {
            "license_module_type": "NATIVE_WEB_SERVER",
            "number_of_licenses": 100
        },
        {
            "license_module_type": "NATIVE_SDK",
            "number_of_licenses": 100
        },
        {
            "license_module_type": "DOT_NET",
            "number_of_licenses": 100
        },
        {
            "license_module_type": "NETVIZ",
            "number_of_licenses": 100
        },
        {
            "license_module_type": "MACHINE_AGENT",
            "number_of_licenses": 100
        },
        {
            "license_module_type": "NODEJS",
            "number_of_licenses": 100
        },
        {
            "license_module_type": "SIM_MACHINE_AGENT",
            "number_of_licenses": 100
        },
        {
            "license_module_type": "PHP",
            "number_of_licenses": 100
        },
        {
            "license_module_type": "PYTHON",
            "number_of_licenses": 100
        }
    ],
    "account_id": "8b1e92f2-387c-45b6-9bb5-ebd7f67587d4",
    "access_key": "api845ad-1f3e-4c9b-909b-a3cfa510bfb0",
    "total_licenses": null,
    "peak_usage": null
}

To update the license rules:

Get the payload using any of the available GET methods.
Update accessKeys, entitlements, etc.
Send the PUT request without changing other key-value pairs.
"version" should be kept as it was during GET. This would be incremental.

Deletes a License Rule

URL

http://<host>:<port>/controller/mds/v1/license/rules/f36e08e2-5f57-4b8c-9ad2-f18873adcd87

Format

DELETE /controller/mds/v1/license/rules/{id}

Input parameter

Parameter Name	Parameter Type	Value	Mandatory
`LicenseRuleId`	Path	Deletes license rule by its ID.	Yes

Retrieve a License Rule by ID

Use this to retrieve a license rule by the license rule ID.

URL

http://<host>:<port>/mds/v1/license/rules/f36e08e2-5f57-4b8c-9ad2-f18873adcd87

Format

GET /mds/v1/license/rules/{licenseRuleId}

Path Parameter

Parameter Name	Parameter Type	Value	Mandatory
`licenseRuleId`	Path	Retrieves the UUID of the license rule.	Yes

Output Parameters

Parameter Name	Parameter Type	Value	Mandatory
id	String	String representing the ID or name.	Yes
version	Integer	Indicates the version number.	Yes
total_licenses	Integer	Integer indicating the total number of licenses.	Yes
account_id	String	Provides the account name or account ID.	Yes
access_key	path	Provides the account access key.	Yes

Example

curl -X GET --user <user>@<AccountName>:<password> http://<host>:<port>/controller/mds/v1/license/rules/091116a4-124c-4b73-9343-f315836f103b

{
    "id": "091116a4-124c-4b73-9343-f315836f103b",
    "version": 0,
    "name": "Default",
    "description": null,
    "enabled": true,
    "constraints": [],
    "entitlements": [
        {
            "license_module_type": "JAVA",
            "number_of_licenses": 100
        },
        {
            "license_module_type": "NATIVE_WEB_SERVER",
            "number_of_licenses": 100
        },
        {
            "license_module_type": "NATIVE_SDK",
            "number_of_licenses": 100
        },
        {
            "license_module_type": "DOT_NET",
            "number_of_licenses": 100
        },
        {
            "license_module_type": "NETVIZ",
            "number_of_licenses": 100
        },
        {
            "license_module_type": "MACHINE_AGENT",
            "number_of_licenses": 100
        },
        {
            "license_module_type": "NODEJS",
            "number_of_licenses": 100
        },
        {
            "license_module_type": "SIM_MACHINE_AGENT",
            "number_of_licenses": 100
        },
        {
            "license_module_type": "PHP",
            "number_of_licenses": 100
        },
        {
            "license_module_type": "PYTHON",
            "number_of_licenses": 100
        }
    ],
    "account_id": "8b1e92f2-387c-45b6-9bb5-ebd7f67587d4",
    "access_key": "bd3845ad-1f3e-4c9b-909b-a3cfa510bfb0",
    "total_licenses": null,
    "peak_usage": null
}

The "version" gets updated after every update from UI or API.

Retrieves a License Rule by Access Key

URL

http://<host>:<port>/controller/mds/v1/license/rules/accessKey/account-accesskey-123

Format

GET /controller/mds/v1/license/rules/accessKey/{accessKey}

Path Parameter

Parameter Name	Parameter Type	Value	Mandatory
access_key	Path	Retrieves the access key assigned to the license rule.	Yes

Output Parameters

Parameter Name	Parameter Type	Value	Mandatory
id	String	String representing the ID or name.	Yes
version	Integer	Indicates the version number.	Yes
total_licenses	Integer	Integer indicating the total number of licenses.	Yes
account_id	String	Provides the account name or account ID.	Yes

Example

curl -X GET --user <user>@<AccountName>:<password> http://<host>:<port>/controller/mds/v1/license/rules

[
    {
        "id": "221116a4-124c-4b73-9343-f315836f103b",
        "version": 0,
        "name": "Default",
        "description": null,
        "enabled": true,
        "constraints": [],
        "entitlements": [],
        "account_id": "8b1e92f2-387c-45b6-9bb5-ebd7f67587d4",
        "access_key": "bd3845ad-1f3e-4c9b-909b-a3cfa510bfb0",
        "total_licenses": 1000,
        "peak_usage": null
    },
    {
        "id": "321116a4-124c-4b73-9343-f315836f103b",
        "version": 0,
        "name": "Custom1",
        "description": null,
        "enabled": true,
        "constraints": [],
        "entitlements": [],
        "account_id": "8b1e92f2-387c-45b6-9bb5-ebd7f67587d4",
        "access_key": "api845ad-1f3e-4c9b-909b-a3cfa510bfb0",
        "total_licenses": 1000,
        "peak_usage": null
    }
]

Retrieve a License Rule by Name

URL

http://<host>:<port>/controller/mds/v1/license/rules/name/Default

Format

GET /controller/mds/v1/license/rules/name/{name}

Path Parameter

Parameter Name	Parameter Type	Value	Mandatory
`name`	Path	Retrieves the name of the license rule.	Yes

Output Parameters

Parameter Name	Parameter Type	Value	Mandatory
id	String	String representing the ID or name.	Yes
version	Integer	Indicates the version number.	Yes
total_licenses	Integer	Integer indicating the total number of licenses.	Yes
account_id	String	Provides the account name or account ID.	Yes

Example

curl -X GET --user <user>@<AccountName>:<password> http://<host>:<port>/controller/mds/v1/license/rules

 [
    {
        "id": "221116a4-124c-4b73-9343-f315836f103b",
        "version": 0,
        "name": "Default",
        "description": null,
        "enabled": true,
        "constraints": [],
        "entitlements": [],
        "account_id": "8b1e92f2-387c-45b6-9bb5-ebd7f67587d4",
        "access_key": "bd3845ad-1f3e-4c9b-909b-a3cfa510bfb0",
        "total_licenses": 1000,
        "peak_usage": null
    },
    {
        "id": "321116a4-124c-4b73-9343-f315836f103b",
        "version": 0,
        "name": "Custom1",
        "description": null,
        "enabled": true,
        "constraints": [],
        "entitlements": [],
        "account_id": "8b1e92f2-387c-45b6-9bb5-ebd7f67587d4",
        "access_key": "api845ad-1f3e-4c9b-909b-a3cfa510bfb0",
        "total_licenses": 1000,
        "peak_usage": null
    }
]