Licenses

Licenses are the core part of Unlocktopus — they allow you to manage and control access to your products. On this page, we'll dive into the different license endpoints you can use to manage licenses programmatically. We'll look at how to query, create, update, validate and revoke licenses.

The License model

The license model contains all the information about your licenses, such as their key, status, and expiration date. It also contains a reference to the associated product.

Properties

id
id
Type
string
Description
Unique identifier for the license.
key
key
Type
string
Description
The license key.
maxActivations
maxActivations
Type
integer | null
Description
The maximum number of activations allowed for the license. If the license has unlimited activations, this value is null.
status
status
Type
string
Description
The license status. Either active, revoked, or expired. If multiple statuses apply, the first in the list takes precedence. For example: If the license is expired and revoked, the status will be revoked. You can check statusDetails for the individual flags.
expirationDate
expirationDate
Type
string | null
Description
The expiration date of the license
createdAt
createdAt
Type
string
Description
Timestamp of when the license was created.
updatedAt
updatedAt
Type
string
Description
Timestamp of when the license was last updated.
productId
productId
Type
string
Description
Unique identifier for the product associated with the license.
statusDetails
statusDetails
Type
object
Description
An object containing more information about the license status at the time of the response.
statusDetails.isRevoked
statusDetails.isRevoked
Type
boolean
Description
Whether the license has been revoked.
statusDetails.isExpired
statusDetails.isExpired
Type
boolean
Description
Whether the license has expired. This is calculated using the expirationDate field.
statusDetails.determinedAt
statusDetails.determinedAt
Type
string
Description
The time when the license status was determined (=response time)

Example License Object

{
  "id": "49cdf099-94ca-4da9-b07a-71d21a7c918a",
  "object": "License",
  "key": "ABCD-1234-EFGH-5678",
  "maxActivations": 10,
  "status": "active",
  "expirationDate": "2029-12-31T23:59:59Z",
  "createdAt": "2023-01-01T00:00:00Z",
  "updatedAt": "2023-01-01T00:00:00Z",
  "productId": "40833d2f-3dc8-4d8a-a5c5-7715043362fc",
  "statusDetails": {
    "isRevoked": false,
    "isExpired": false,
    "determinedAt": "2024-09-26T11:28:34Z",
  },
}

GET/licenses

List all licenses

This endpoint allows you to retrieve a paginated list of your licenses. If you use a product-specific API key, only licenses for that product will be returned. See Pagination for more information on pagination.

Optional attributes

page
page
Type
integer
Description
Page number for pagination.
limit
limit
Type
integer
Description
Limit the number of licenses returned.
sort
sort
Type
string (field:order)
Description
Sort the results by the given field and order.
productId
productId
Type
string
Description
Only return licenses for the specified product. If you do not provide a product ID, all licenses across all your products will be returned.
filter
filter
Type
string
Description
Filter the results with more advanced rules.

https://api.unlocktopus.com

Request

GET

/v0/licenses

curl -G https://api.unlocktopus.com/api/v0/licenses \
  -H "Authorization: Bearer {token}" \
  -d limit=5 \
  -d productId="4e269bf8-e9a1-4049-b423-3abda9947f9e"

Example Response

{
  "data": [
    {
      "id": "49cdf099-94ca-4da9-b07a-71d21a7c918a",
      "object": "License",
      "key": "ABCD-1234-EFGH-5678",
      "maxActivations": 10,
      "status": "revoked",
      "expirationDate": "2029-12-31T23:59:59Z",
      "createdAt": "2023-01-01T00:00:00Z",
      "updatedAt": "2023-01-01T00:00:00Z",
      "productId": "40833d2f-3dc8-4d8a-a5c5-7715043362fc",
      "statusDetails": {
        "isRevoked": true,
        "isExpired": false,
        "determinedAt": "2024-09-26T11:28:34Z",
      },
    },
    // ...
  ],
  "totalCount": 50,
  "page": 0,
  "limit": 5,
  "totalPages": 10,
  "hasPrevPage": false,
  "hasNextPage": true,
  "prevPage": null,
  "nextPage": 1
}

POST/licenses

Create a license

This endpoint allows you to create a new license. To create a license, you must provide the product ID and optionally specify the maximum activations and expiration date.

If you need a license token, e.g. for offline validation, you need to generate it with the /licenses/:id/tokens endpoint afterwards.

Required attributes

productId
productId*
Type
string
Description
The ID of the product for which the license is being created.

Optional attributes

maxActivations
maxActivations
Type
integer | null
Description
The maximum number of activations allowed for the license. Defaults to 1. For unlimited activations, set this to null.
expirationDate
expirationDate
Type
string | null
Description
The expiration date of the license. Must be in the future. Set to null to disable expiration.

Request

POST

/v0/licenses

curl https://api.unlocktopus.com/api/v0/licenses \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "40833d2f-3dc8-4d8a-a5c5-7715043362fc",
    "maxActivations": 5,
    "expirationDate": "2029-12-31T23:59:59Z",
  }'

Response

{
  "id": "49cdf099-94ca-4da9-b07a-71d21a7c918a",
  "object": "License",
  "key": "ABCD-1234-EFGH-5678",
  "maxActivations": 10,
  "status": "active",
  "expirationDate": "2029-12-31T23:59:59Z",
  "createdAt": "2023-01-01T00:00:00Z",
  "updatedAt": "2023-01-01T00:00:00Z",
  "productId": "40833d2f-3dc8-4d8a-a5c5-7715043362fc",
  "statusDetails": {
    "isRevoked": false,
    "isExpired": false,
    "determinedAt": "2024-09-26T11:28:34Z",
  },
}

PATCH/licenses/:id

Update a license

This endpoint allows you to update a license's details by its unique ID.

Optional attributes

maxActivations
maxActivations
Type
integer
Description
The new maximum number of activations allowed for the license.
expirationDate
expirationDate
Type
string
Description
The new expiration date of the license.

Request

PATCH

/v0/licenses/:id

curl -X PATCH https://api.unlocktopus.com/api/v0/licenses/777ceaea-c94d-493b-ba66-1f92f9c2841b \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "maxActivations": 15,
    "expirationDate": "2025-12-31T23:59:59Z"
  }'

Response

{
  "id": "49cdf099-94ca-4da9-b07a-71d21a7c918a",
  "object": "License",
  "key": "ABCD-1234-EFGH-5678",
  "maxActivations": 15,
  "status": "active",
  "expirationDate": "2025-12-31T23:59:59Z",
  "createdAt": "2023-01-01T00:00:00Z",
  "updatedAt": "2023-01-01T00:00:00Z",
  "productId": "40833d2f-3dc8-4d8a-a5c5-7715043362fc",
  "statusDetails": {
    "isRevoked": false,
    "isExpired": false,
    "determinedAt": "2024-09-26T11:28:34Z",
  },
}

GET/licenses/:id

Retrieve a license

This endpoint allows you to retrieve a license by its unique ID.

Do not use this endpoint to validate a license by checking its status. Use the /licenses/validate endpoint instead.

Request

GET

/v0/licenses/:id

curl -G https://api.unlocktopus.com/api/v0/licenses/:id \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "49cdf099-94ca-4da9-b07a-71d21a7c918a",
  "object": "License",
  "key": "ABCD-1234-EFGH-5678",
  "maxActivations": 15,
  "status": "active",
  "expirationDate": "2025-12-31T23:59:59Z",
  "createdAt": "2023-01-01T00:00:00Z",
  "updatedAt": "2023-01-01T00:00:00Z",
  "productId": "40833d2f-3dc8-4d8a-a5c5-7715043362fc",
  "statusDetails": {
    "isRevoked": false,
    "isExpired": false,
    "determinedAt": "2024-09-26T11:28:34Z",
  },
}

POST/licenses/:id/tokens

Generate a license token

This endpoint allows you to generate a license token for a specific license. This token can be validated offline. A license token always contains the license ID and the expiration date, but can optionally contain additional payload data.

Required attributes

id
id*
Type
string
Description
The ID of the license to generate a token for.

Optional attributes

customPayload
customPayload
Type
object
Description
The (additional) payload to include in the token. The larger the payload, the longer the token.

Request

/v0/licenses/:id/tokens

curl -X POST https://api.unlocktopus.com/api/v0/licenses/:id/tokens \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
  "customPayload": {
    "featureFlags": ['feature1', 'feature2']
  }
}'

Response

{
  "token": "[a long string]",
  "payload": {
    "licenseId": "777ceaea-c94d-493b-ba66-1f92f9c2841b",
    "expirationDate": "2026-12-31T23:59:59Z",
    "productId": "40833d2f-3dc8-4d8a-a5c5-7715043362fc",
    "createdAt": "2023-01-01T00:00:00Z",
    "customFields" : {
      "featureFlags": ["feature1", "feature2"]
    }
  },
  "license": {
    "id": "49cdf099-94ca-4da9-b07a-71d21a7c918a",
    "object": "License",
    "key": "ABCD-1234-EFGH-5678",
    "maxActivations": 15,
    "status": "active",
    "expirationDate": "2025-12-31T23:59:59Z",
    "createdAt": "2023-01-01T00:00:00Z",
    "updatedAt": "2023-01-01T00:00:00Z",
    "productId": "40833d2f-3dc8-4d8a-a5c5-7715043362fc",
    "statusDetails": {
      "isRevoked": false,
      "isExpired": false,
      "determinedAt": "2024-09-26T11:28:34Z"
    },
  }
}

POST/licenses/validate-key

Validate a license key

This endpoint allows you to validate a license by its key for a specific product.

See SDK's for more information on client-side validation.

Parameters

key
key*
Type
string
Description
The license key to validate.
productId
productId*
Type
string
Description
The unique identifier of the Product that the License belongs to.

Response fields

isValid
isValid
Type
boolean
Description
Whether the license key is valid.
reason
reason
Type
string
Description
null, if license is valid. One of expired, revoked and suspended if license is invalid.
timestamp
timestamp
Type
string
Description
The timestamp of the validation.
license
license
Type
object
Description
The license object.

Request

POST

/v0/licenses/validate-key

curl https://api.unlocktopus.com/api/v0/licenses/validate \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"key": "ABCD-1234-EFGH-5678",
"productId": "40833d2f-3dc8-4d8a-a5c5-7715043362fc"
}'

Response

{
  "isValid": true,
  "reason": null,
  "timestamp": "2024-09-09T00:00:00Z",
  "license": {
    "id": "49cdf099-94ca-4da9-b07a-71d21a7c918a",
    "object": "License",
    "key": "ABCD-1234-EFGH-5678",
    "maxActivations": 15,
    "status": "active",
    "expirationDate": "2025-12-31T23:59:59Z",
    "createdAt": "2023-01-01T00:00:00Z",
    "updatedAt": "2023-01-01T00:00:00Z",
    "productId": "40833d2f-3dc8-4d8a-a5c5-7715043362fc",
    "statusDetails": {
      "isRevoked": false,
      "isExpired": false,
      "determinedAt": "2024-09-26T11:28:34Z"
    },
  }
}

Validate a license offline

If your license is set up for offline validation, you can use our SDKs to validate the license token offline. This requires you to configure the SDK with your public (product) key.

This method returns the encoded token payload.

See JavaScript Client SDK documentation for more information on client-side (offline) validation.

SDK Token Validation

import UnlocktopusClient from 'unlocktopus-client';

const unlocktopus = new UnlocktopusClient({
  productId: '40833d2f-3dc8-4d8a-a5c5-7715043362fc',
  publicKey: '[PUBLIC_KEY]',
  licenseToken: "[LICENSE_TOKEN",
});

await unlocktopus.validateTokenOffline({
  licenseToken: '[LICENSE_TOKEN]'
});

Return value

{
  "licenseId": "49cdf099-94ca-4da9-b07a-71d21a7c918a",
  "expiresAt": "2025-12-31T23:59:59Z",
  "productId": "40833d2f-3dc8-4d8a-a5c5-7715043362fc",
}

POST/licenses/:licenseId/revoke

Revoke a license

Revoked a license specified by its ID. Revoked licenses can be reinstated.

Required attributes

id
id*
Type
string
Description
The ID of the license to revoke.

Request

/licenses/:licenseId/revoke

curl -X POST https://api.unlocktopus.com/api/v0/licenses/:id/revoke \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json"

Response

{
  "id": "49cdf099-94ca-4da9-b07a-71d21a7c918a",
  "object": "License",
  "key": "ABCD-1234-EFGH-5678",
  "maxActivations": 15,
  "status": "revoked",
  "expirationDate": "2026-12-31T23:59:59Z",
  "createdAt": "2023-01-01T00:00:00Z",
  "updatedAt": "2023-01-01T00:00:00Z",
  "productId": "40833d2f-3dc8-4d8a-a5c5-7715043362fc",
  "statusDetails": {
    "isRevoked": true,
    "isExpired": false,
    "determinedAt": "2024-09-26T11:28:34Z"
  },
}

POST/licenses/:id/reinstate

Reinstate a license

Reinstating a license allows it to be validated or activated again.

Required attributes

id
id*
Type
string
Description
The ID of the license to reinstate.

Request

/licenses/:id/reinstate

curl -X POST https://api.unlocktopus.com/api/v0/licenses/:id/reinstate \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json"

Response

{
  "id": "49cdf099-94ca-4da9-b07a-71d21a7c918a",
  "object": "License",
  "key": "ABCD-1234-EFGH-5678",
  "maxActivations": 15,
  "status": "revoked",
  "expirationDate": "2026-12-31T23:59:59Z",
  "createdAt": "2023-01-01T00:00:00Z",
  "updatedAt": "2023-01-01T00:00:00Z",
  "productId": "40833d2f-3dc8-4d8a-a5c5-7715043362fc",
  "statusDetails": {
    "isRevoked": true,
    "isExpired": false,
    "determinedAt": "2024-09-26T11:28:34Z"
  },
}