Provision licenses

In essence, software licenses represent the terms and conditions of use for your applications. With 10Duke Enterprise, you can provision (grant) licenses at the user level or at the organization level.

You may have use cases where you want to provision licenses (of any type) manually. Using 10Duke SysAdmin, you can easily grant licenses to both organizations and users.

However, you will more commonly rely on the 10Duke Entitlement Management REST API and CRUD operations to automate the provisioning of licenses.

When provisioning licenses to an organization through the Entitlement Management REST API, you can specify the entitlement where they will be placed. Otherwise they are placed in the organization’s default entitlement. A default entitlement is automatically created for the organization if it doesn’t have one yet. Similarly, provisioning licenses to a user also creates an entitlement for them if they don’t have one yet.

The articles in this section cover examples on how to provision the most common license types through the Entitlement Management REST API.

API operations

10Duke Entitlement Management REST API operations for provisioning and updating licenses:

Operation URL (relative, prepend the environment base URL)
Provision licenses to an organization POST /organizations/{orgId}/license-transactions
Provision personal licenses to a user POST /users/{userId}/license-transactions
Update the organization licenses in a license transaction PUT /organizations/{orgId}/license-transactions
Update the personal licenses in a license transaction PUT /users/{userId}/license-transactions

Provision licenses in a transaction

When provisioning licenses, you use a transaction structure that can group multiple license grants together if needed.

This JSON example request body shows a simple transaction that contains the essential information for provisioning licenses using a single product package:

{
   "transaction": {
      "type": "Order",
      "externalId": "0000004556786",
      "items": [
         {
            "externalId": "0005404526916",
            "productId": "57042763-559c-4503-8db2-432d4fe82431",
            "quantity": 10,
            "licenseValidFrom": "2023-05-31T14:12:22.012Z",
            "licenseValidUntil": "2024-05-31T14:12:22.012Z"
         }
      ]
   }
}

At both the transaction and the transaction item level, use externalId to specify IDs used in your external system, such as IDs related to the customer’s order. These are the IDs that will be used in later API communications to identify the transaction and the transaction items.

The example transaction above contains one transaction item in items.

  • In productId, specify the ID of the product package to use for provisioning the licenses. (Alternatively, you could identify the product package by name using productName.)

  • In quantity, specify the requested product package quantity.

    Whether this quantity will be reflected as seats, use count, or use time in the licenses depends on the licensed items’ settings in the product package. They define the type and amount of credit included in the product package for each licensed item.

    For example, if the product package includes 50 seats for each licensed item, the example request above with quantity set to 10 would grant 500 seats in each license.

  • In licenseValidFrom and (optional) licenseValidUntil, specify the validity period for the licenses.

See more details on the fields in the API reference.

Now, let’s say your customer purchased two products at a time. To provision licenses with two product packages in one transaction, items now contains two transaction items, each specifying the provisioning information for one product package.

{
   "transaction": {
      "type": "Order",
      "externalId": "0000004556786",
      "items": [
         {
            "externalId": "0005404526916",
            "productId": "57042763-559c-4503-8db2-432d4fe82431",
            "quantity": 10,
            "licenseValidFrom": "2023-05-31T14:12:22.012Z",
            "licenseValidUntil": "2024-05-31T14:12:22.012Z"
         },
         {
            "externalId": "0005404526917",
            "productId": "7a195f0b-459b-4c60-ba5e-7a3d53133e28",
            "quantity": 15,
            "licenseValidFrom": "2023-05-31T14:12:22.012Z",
            "licenseValidUntil": "2024-05-31T14:12:22.012Z"
         }
      ]
   }
}

Regarding later changes to a transaction:

  • When you update licenses related to a transaction, the request uses the same transaction structure as when provisioning licenses (see above).

    In the externalId fields in the update request, identify the transaction and the transaction items using the corresponding externalId IDs that you specified during provisioning.

  • When retrieving a transaction, or when suspending or resuming the licenses related to a transaction, you only identify the transaction.

    In the transactionExternalId path parameter in the request, specify the ID that you specified in externalId at the transaction level when you provisioned the licenses.

On this page