Skip to content
Identity and Access Management

Certificate Rotation - Limits

In order to prevent identities (misconfigured/ faulty/ rogue) from over utilizing the underlying IAM resources, the following quota limits will apply to Bootstrap API and Application PATCH API

###Success Rotation Lock

  • Each identity can make a maximum of 10 successful certificate requests in a 24 hour window.

  • Beyond which, the identity’s status will change to SuccessRotationLock and successive requests in the next 24 hours will receive the below response.

    Status Code: 400: BAD REQUEST
      Response:
      {
        "type": "https://docs.trimblecloud.com/identity-and-access-management/content/reference/errors/api_errors/",
        "title": "validation_error",
        "status": "400",
        "detail": "Device reached certificate rotation limit. Next certificate rotation can be requested after 2025-08-12T06:10:25Z"
      }

  • In ideal scenarios, identities usually make only 1 certificate request during initial provisioning or during certificate expiry(every 3 years).

###Failure Rotation Lock

  • Identity configuration will be locked after 10 consecutive failure requests in a 24 hour window.

  • Identity’s status will change to FailureRotationLock and successive requests in the next 24 hours will receive the below response.

     Status Code: 400: BAD REQUEST
      Response:
      {
        "type": "https://docs.trimblecloud.com/identity-and-access-management/content/reference/errors/api_errors/",
        "title": "validation_error",
        "status": "400",
        "detail": "Device locked due to exceeding failure certificate rotation limit. Please unlock device or next certificate rotation can be requested after 2025-08-12T06:10:25Z"
      }

##Entity Certificate Lock Status ###Device Device certificate lock status can be retrieved from GET Device API / List Devices API, by setting the query parameter include=full. This returns the certRotationLock field in the response.

####GET Device

GET {base URL}/devices/{deviceId}?include=full

####GET Devices

GET {base URL}/devices?include=full

Response 200 OK

{
    "metadata": {
        "createdBy": "trn:2:iam:us:user:bc475617-rd16-4d32-a25c-f360b414d587",
        "createdAt": "2025-04-23T18:58:50.008000Z",
        "updatedBy": "trn:2:iam:us:user:bc475617-rd16-4d32-a25c-f360b414d587",
        "updatedAt": "2025-04-23T18:58:50.008000Z"
    },
    "serialNumber": "12345",
    "manufacturer": "Trimble",
    "model": "Tablet",
    "sku": "1342AM2",
    "publicKey":"-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAETLSvsnQYK8DKH5+zQqEwgp/ctpOy\nnQg9Px0y6cyH8KZkb0RAGE75YCuAJl1HJzuiW2FtqRJtGY49BzKSN1S2rQ==\n-----END PUBLIC KEY-----",
    "id": "3a10a36e-12ea-4c98-aa57-3e970bcea56c",
    "trn": "trn:2:iam:us:device:3a10a36e-12ea-4c98-aa57-3e970bcea56c",
    "certRotationLock": true,
    "accounts": {
        "current": {
            "id": "c9c5d208-94d9-48b2-8d91-f0ec34725093",
            "name": "Corporate DX"
        },
        "previous": {
            "id": "c0d32b11-6499-468f-88cd-4f0148fefb80",
            "name": "Civil Systems"
        }
    },
    "status": "BLOCKED",
    "statusMetaData": {
        "reason": "Stolen",
        "comment": "device is blocked"
    },
    "purchaseOrderNumber":"PO123456",
    "salesOrderNumber":"SO123456",
    "friendlyName": "Survey Rover - Site A"
}

If the certRotationLock=true, then the device is in locked state and needs to be unlocked in order to continue with certificate rotation (within 24hrs window).

####Unlock Device

Device PATCH API could be used to unlock Devices that are locked because of SuccessRotationLock or FailureRotationLock, enabling certificate requests to be processed immediately without waiting for 24 hours.

###Application Application certificate lock status can be retrieved from GET Application API / List Applications API, by setting the query parameter include=full. This returns the certRotationLock field in the response.

####GET Application

GET {base URL}/devices/{deviceId}/applications/{applicationId}?include=full

####GET Applications of a Device

GET {base URL}/devices/{deviceId}/applications?include=full

Response 200 OK

{
    "metadata": {
        "createdBy": "trn:2:iam:us:device:b2cbfd1f-af0c-42f5-9cdf-1029f9a3ee07",
        "createdAt": "2025-12-04T15:36:52.708000Z",
        "updatedBy": "trn:2:iam:us:device:b2cbfd1f-af0c-42f5-9cdf-1029f9a3ee07",
        "updatedAt": "2025-12-04T15:36:52.708000Z"
    },
    "id": "026a24df-8b88-4617-b68a-e58bc8468ff2",
    "applicationName": "application-3489",
    "description": "test Description",
    "certificate": "-----BEGIN CERTIFICATE----- MIIDXTCCAkWgAkiG9w0BAQsFAwIBAgIJALa6+2y+0zANBgkqhDBoMQswCQYDVQQG... -----END CERTIFICATE-----",
    "displayName": "test application",
    "subscriptionScopes": [
        "iam-test", "iot-test-app"
    ],
    "trn": "trn:2:iam:us:application:026a24df-8b88-4617-b68a-e58bc8468ff2",
    "certRotationLock": true
}

If the certRotationLock=true, then the application is in locked state and needs to be unlocked in order to continue with certificate rotation (within 24hrs window).

####Unlock Application

Application PATCH API could be used to unlock application that are locked because of SuccessRotationLock or FailureRotationLock, enabling certificate requests to be processed immediately without waiting for 24 hours.

##Device Certificate Limit

Each device can have a maximum of 5 associated certificates, including those issued through the Bootstrap API and the Device Cert API

When this limit is reached, the IAM Bootstrap API returns the following error:

{
    "type": "https://docs.trimblecloud.com/identity-and-access-management/content/reference/errors/api_errors/",
    "title": "validation_error",
    "status": "400",
    "detail": "Device already has 5 certificates mapped"
}

To enable certificate rotation for a device that has reached this limit, an existing certificate must first be deleted using the DELETE Cert API