Consume a license

You use the same kind of a request to the 10Duke License Consumption API endpoint /authz/ to both consume a license and to renew an existing license lease.

The only difference in the parameters is that depending on the license model, the renewal request may also need to specify the lease ID included in the license token.

You can request license consumption or lease renewal for one or multiple licensed items in a single request.

Both requests return the same response.

Request syntax

The request syntax is slightly different depending on your use case.

Request syntax for one licensed item

Syntax for a first-time license consumption request for one licensed item (line breaks added for display purposes):

<BASE_URL>/authz/[.jwt|.json|.txt]
   ?<item_1>
   [&doConsume=true]
   [&consumptionMode=consumption_mode]
   [&consumeDuration=consume_duration]
   [&consumeCount=consume_count]
   [&hw=hw_id[;name=hw_name]]
   [&process=process_id[;name=process_name]]
   [&version=version]
   [&ownerOrganizationId=organization_ID|ownerUserId=user_ID|entitlementId=entitlement_ID|licenseId=license_ID]

Syntax for renewing a lease for one licensed item:

<BASE_URL>/authz/[.jwt|.json|.txt]
   ?<item_1>
   [&doConsume=true]
   [&consumptionMode=consumption_mode]
   [&consumeDuration=consume_duration]
   [&consumeCount=consume_count]
   [&hw=hw_id[;name=hw_name]]
   [&process=process_id[;name=process_name]]
   [&version=version]
   [&leaseId=lease_id]
   [&ownerOrganizationId=organization_ID|ownerUserId=user_ID|entitlementId=entitlement_ID|licenseId=license_ID]

Request syntax for multiple licensed items

Syntax for a first-time license consumption request for multiple licensed items (line breaks added for display purposes):

<BASE_URL>/authz/[.jwt|.json|.txt]
   ?<item_1>[=;ownerOrganizationId=organization_ID|ownerUserId=user_ID|entitlementId=entitlement_ID|licenseId=license_ID]
   [[&item_2][=;ownerOrganizationId=organization_ID|ownerUserId=user_ID|entitlementId=entitlement_ID|licenseId=license_ID]]
   [&doConsume=true]
   [&consumptionMode=consumption_mode]
   [&consumeDuration=consume_duration]
   [&consumeCount=consume_count]
   [&hw=hw_id[;name=hw_name]]
   [&process=process_id[;name=process_name]]
   [&version=version]

Syntax for renewing a lease for multiple licensed items:

<BASE_URL>/authz/[.jwt|.json|.txt]
   ?<item_1>[=;leaseId=lease_id][;ownerOrganizationId=organization_ID|ownerUserId=user_ID|entitlementId=entitlement_ID|licenseId=license_ID]
   [[&item_2][=;leaseId=lease_id][;ownerOrganizationId=organization_ID|ownerUserId=user_ID|entitlementId=entitlement_ID|licenseId=license_ID]]
   [&doConsume=true]
   [&consumptionMode=consumption_mode]
   [&consumeDuration=consume_duration]
   [&consumeCount=consume_count]
   [&hw=hw_id[;name=hw_name]]
   [&process=process_id[;name=process_name]]
   [&version=version]

Request parameters

In <BASE_URL>, enter the base URL of your 10Duke Enterprise environment.

Replace the parameters in the URL with actual values. The <> notation is used for mandatory variables and [] for optional ones.

Include the authorization header in the request.

See details below on the path and query parameters.

Path parameters

.jwt|.json|.txt: Define the format in which you want the response. If you don’t specify a format, plain text is used.

Query parameters

• item_N: The name of the licensed item to check.

  The licensed item can be either a top-level item (usually representing a product) or an aggregated licensed item (usually representing a feature).

  The licensed item is also used for anchoring if the license model defines licensed items as a session or lease anchor. See more information on anchors in the ConcurrentSessions constraint in the license model.

• doConsume (optional): Define whether the request is to consume the license or only to check license availability.

  Possible values:

  • true: Consume the license. This is the default if the parameter is not provided.

  • false: Only check if the license is available for consumption without actually consuming it.

• consumptionMode (optional): The license consumption mode requested.

  • cache: Online mode. This is the default if the parameter is not provided.

    This is intended to be used by online client applications that are able to check and refresh the license token frequently to renew the license lease, and don’t need to store license tokens for a long period of time.

    We recommend that the license model defines a shorter maximum lease validity for online use (from minutes up to typically a maximum of 24 hours). To get a license token with a shorter validity time, the client application can use the cache option in the request.

  • checkout: Offline mode.

    This is intended to be used with client applications that go offline for longer periods of time.

    We recommend that the license model defines a longer maximum lease validity for offline use (days, weeks, months, or even years, depending on the use case). To get a license token with a longer validity time, the client application can use the checkout option in the request.

    See also use cases on supporting offline usage.

  See more information on the LeaseTimeBehavior constraint in the license model.

• consumeDuration (optional): The requested duration of the license token (and the lease) in milliseconds.

  Instead of relying on receiving the maximum lease validity configured in the license model, the client application can request a specific duration. This usually requires input from the end user who is asking for a specific duration.

  The granted duration may be shorter than what was requested because it cannot exceed the maximum lease validity (for online or offline use) defined in the license model nor the validity of the license itself.

  See more information on the LeaseTimeBehavior constraint in the license model.

• consumeCount (optional): The requested number of units to be consumed from the license’s use count. The value must be a positive integer.

• Hardware parameters:

  • hw (optional): The hardware ID of the client device.

    This is a mandatory parameter in the following cases:

    • When consuming licenses where the license model limits the number of devices allowed per seat. See more information on anchors in the ConcurrentSessions constraint in the license model.

    • When consuming licenses for which the license model specifies the ConsumptionLockConstraint rule, for example, to prevent the abuse of trial licenses.

    Note: We recommend that you provide the hardware ID when possible.

  • name (optional): A human-readable name of the hardware or device.

• Process parameters:

  • process (optional): The process ID of the client application requesting the license.

    This information is needed if the license model uses processes as a session or lease anchor. See more information on anchors in the ConcurrentSessions constraint in the license model.

  • name (optional): The name of the client application requesting the license.

• version (optional): The version of the software that is running on the device, typically expressed as a version number (for example, 1.6.14).

  This information is needed if the license model uses versions as a session or lease anchor. See more information on anchors in the ConcurrentSessions constraint in the license model.

• leaseId (optional): In a license renewal request, the ID of the license lease to be extended. This is effectively the value of the JSON Web Token ID (JTI) claim of the previous license check.

  This parameter is mandatory on renewal if lease chaining is enforced. See more information on enforcing lease chaining in the ConcurrentSessions constraint in custom license models.

  Note: We recommend that you provide the lease ID when possible.

• To limit which licenses can be consumed if multiple ones are available, one of the following parameters can be used:

  • ownerOrganizationId (optional): An organization ID to only consume that organization’s licenses.

  • ownerUserId (optional): A user ID to only consume that user’s personal licenses.

  • entitlementId (optional): An entitlement ID to only consume licenses in that entitlement.

  • licenseId (optional): A license ID to only consume a specific license.

You can get organization, entitlement, and license IDs, for example, by querying the user’s or device client’s available licenses through the 10Duke Entitlement Management REST API.

Request examples

For example, you could make an HTTP GET request to consume the license for licensed item “AppFeature-XYZ” in online mode (line breaks added for display purposes):

<BASE_URL>/authz/.jwt
   ?AppFeature-XYZ
   &hw=T29qb1RoYWU3aWV6MENoYWlkaWUyZXRoMWphMmFoQmUK

To renew the license lease for that licensed item:

<BASE_URL>/authz/.jwt
   ?AppFeature-XYZ
   &hw=T29qb1RoYWU3aWV6MENoYWlkaWUyZXRoMWphMmFoQmUK
   &leaseId=d04551aa-7c0a-47a6-aa85-ed345e591ea9

To renew the license lease for multiple licensed items in the same request:

<BASE_URL>/authz/.jwt
   ?AppFeature-XYZ=;leaseId=d04551aa-7c0a-47a6-aa85-ed345e591ea9
   &AppFeature-ABC=;leaseId=d82cde79-da02-4e24-861c-ed3bf96a4fed
   &hw=T29qb1RoYWU3aWV6MENoYWlkaWUyZXRoMWphMmFoQmUK

Response

You can request the response in either JSON Web Token (JWT), JSON, or plain text format.

JWT is the most commonly used and the recommended one, because it enables signature validation in the client. For more information on JWT, see jwt.io and RFC 7519.

A JSON response returns the same information as JWT but without a signature, and a plain text response only returns true or false values.

If you specify multiple licensed items in the request, one response object per licensed item is returned. In a JWT response, this means one JWT token per licensed item in an “&”-separated list.

JWT response

The JSON Web Token (JWT) response contains three parts, which are separated by a “.” character. Each part is Base64-encoded.

• The first part is a header that contains, for example, the signature and cryptography method algorithm used, such as {"alg":"RS256"}.

• The second part contains the token payload.

• The third part contains the signature produced of the header and payload.

An example JWT payload that shows fields that can be returned:

{
   "exp": 1675702153,
   "AppFeature-XYZ": true,
   "iss": "https://customer.10duke.net",
   "sub": "9ee24fec-2c53-4171-9285-2c9934e5b559",
   "jti": "269c9f73-229c-4895-bfc2-1827d20bc8d5",
   "iat": 1675701253,
   "ver": "1.6.14",
   "lic": "870f46a4-1faa-4847-955b-14ee5f74f3fe",
   "ibb": 1672531200,
   "ibe": 1704067200,
   "rfr": 1675702093,
   "hw": "T29qb1RoYWU3aWV6MENoYWlkaWUyZXRoMWphMmFoQmUK",
   "licenseProperties": {
        "lang": "en,es",
        "country": "us"
   }
}

The JWT payload contains the following fields (the timestamps are in seconds since the epoch):

• exp: The time when the token expires, based on the token validity defined in the license model

• <item_N>: The name of the licensed item as the field name, and the value true

• iss: The URL of your 10Duke Enterprise deployment, the issuer of the token. Depending on your deployment configuration, iss may specify the sub content instead and the sub field is not included.

• sub: The ID of the end user’s user account or the unique ID of the client

• jti: The token ID, also referred to as the lease ID

• iat: The time when the token was issued (the lease was created)

• ver: The version of the software that was requested in the license consumption call

• lic: The ID of the license consumed

• ibb: The validity start time of the license that this token is consuming

• ibe: The validity end time of the license that this token is consuming

• rfr: The default token refresh time. You can configure your client application to rely on the rfr value to trigger the renewal of the license lease. If the application doesn’t rely on this value, we recommend using a refresh time that is the same as or earlier than the token expiry time.

• hw: If available, the ID of the computer or hardware on which the license is being consumed

• licenseProperties: If available, license properties defined for the license as custom name-value pairs. The license property feature must be enabled in your deployment configuration.

The JWT payload can also contain additional fields related to specific license model constraints as well as custom fields. For more information, contact the 10Duke Integration Support team.

JSON response

The JSON response is a license lease entity serialized as the JSON object.

The JSON response contains the same fields as a JWT response payload.

Plain text response

The plain text response only provides information on whether the user or device client has access to a license item or not. It contains an “&”-separated list of true or false values that map to the list of licensed item name parameters provided in the original request.

Error response

When a license check request results in an identified error situation, for example, a license is not accessible for the authorized user, the API returns a response with HTTP status code 200 and a description of the error situation in the response body.

Example error response:

{
   "licensedItemNameHere_errorKey": "notAuthorized",
   "licensedItemNameHere_errorMessage": "Access to \"licensedItemNameHere\" denied",
   "iss": "9ee24fec-2c53-4171-9285-2c9934e5b559",
   "licensedItemNameHere_errorCode": "notAuthorized",
   "iat": 1675701253,
   "licensedItemNameHere_errorTechnical": "Authorization failed for \"licensedItemNameHere\""
}

Error codes

The following are the possible error codes produced for license checks. The error messages and technical error descriptions are not included below.

A plain text response doesn’t contain an error code, only the value false.