License Enforcement

EMSv4 provides the source of truth for Trimble User (or Device) license assignments. Trimble products are responsible for consuming this data to perform license enforcement within their product or system boundaries.

License enforcement within Trimble products involves two steps:

1. Requesting an access_token that authorizes a client application to retrieve licensing information for TID Users or Devices.
2. Using that access_token to execute a GET request to the EMSv4 /licenses endpoint, which will return a paginated list of licenses for the Trimble Users, Devices, or Applications specified by the request. Trimble products use these returned licenses to authorize access to its features and capabilities.

The /licenses endpoint supports many combinations of query parameters and TID identity types. The most request pattern filters licenses using the sku, featureId,accountId, and status query parameters. Products should use the most restrictive set of query parameters applicable to their use case to minimize the size of the response.

Note

GET /licenses?sku=TEST-BS-SB-TAM-PRODUCT-3&accountId=Test-TAM-EMS-Integration-AccountId&status=active

{
    "items": [
        {
            "holderId": "5d6457ca-ee05-4a36-b111-4612c28317bf",
            "activationDate": "2023-10-12T00:00:00Z",
            "deactivationDate": "2023-11-20T00:00:00Z",
            "sku": "TEST-BS-SB-TAM-PRODUCT-3",
            "entitlement": {
                "version": 1,
                "accountId": "Test-TAM-EMS-Integration-AccountId",
                "sourceSystem": null,
                "product": {
                    "TEST-BS-SB-TAM-PRODUCT-3": {
                        "summary": "Summary for TEST-BS-SB-TAM-PRODUCT-3",
                        "image": "Image URL for TEST-BS-SB-TAM-PRODUCT-3",
                        "customAttribute": null,
                        "urls": {
                            "download": "Download URL for TEST-BS-SB-TAM-PRODUCT-3",
                            "launch": "Launch URL for TEST-BS-SB-TAM-PRODUCT-3",
                            "learning": "Learning URL for TEST-BS-SB-TAM-PRODUCT-3"
                        },
                        "name": "Name for TEST-BS-SB-TAM-PRODUCT-3",
                        "description": "Description for TEST-BS-SB-TAM-PRODUCT-3",
                        "type": [
                            "web"
                        ],
                        "version": 1,
                        "features": [
                            "TEST-FEA-TAM-NON-TRACKABLE"
                        ]
                    }
                },
                "startDate": "2023-10-12T00:00:00",
                "endDate": "2023-11-20T00:00:00",
                "orderId": "OrderForProduct3",
                "origin": "05cd1345-f842-4533-ab56-6daa7c708548",
                "type": "standard",
                "customAttribute": null,
                "active": true,
                "isMaxEnforcement": true,
                "isJobScheduled": false,
                "licenses": {
                    "TEST-BS-SB-TAM-PRODUCT-3": {
                        "inUse": 50,
                        "total": 50
                    }
                },
                "parentId": null,
                "id": "62077a13-f95d-4b0b-be9f-279552d52157",
                "status": "expired"
            },
            "active": true,
            "usage": {
                "TEST-FEA-TAM-NON-TRACKABLE": {
                    "usage": {
                        "max": null,
                        "metric": null,
                        "used": 0
                    }
                }
            },
            "customAttribute": null,
            "id": "00948260-8289-4fb3-8754-1d62e1682256",
            "status": "active",
            "emsSource": "emsv4"
        }
    ],
    "nextPage": "eyJmcm9tX3BhZ2UiOiAiMjJhNGJkNmYtNzc3NC00ODg1LWIyYWEtZjE0ZWViODZlYjM1In0="
}

Trimble products that use Trimble Access Management (TAM) for data authorization can optionally perform EMSv4 license checks directly within the TAM environment using the trimble.entitlement.licenses package. This enhances your EMS v4 integration by enabling license caching and pagination on the product’s behalf