Manage Licenses with REST

Learn how to acquire and manage Nuix licenses.

An authentication token is required to access most endpoints within the Nuix RESTful Service API. To get an authentication token, a request must be submitted to the API to retrieve a license from your configured NMS instance. If the requested license is available on the licensing server, an authentication token will be issued in the request response. This token can then be used during your session to make authenticated calls to the API.

Within this topic, you’ll learn how to:

  1. Identify which Nuix license types are available for use.
  2. Request an authentication token.
  3. Release your license to end your session.

License Availability

Nuix offers several different license types that provide various functionality for different use cases. When submitting a request to retrieve an authentication token, you may want to know what license types are available to you.

Check which Nuix license types are available on your configured NMS instance using the following GET request to the /licenses endpoint.

curl -X GET "http://127.0.0.1:8080/nuix-restful-service/svc/licenses" -H "accept: application/vnd.nuix.v1+json"
{
  "shortname": "enterprise-workstation",
  "count": 8,
  "configuredCount": 10,
  "description": "Nuix eDiscovery Workstation",
  "workers": 6,
  "configuredWorkers": 10,
  "audited": false,
  "auditThreshold": 0,
  "source": null,
  "type": null,
  "location": null,
  "expiry": null,
  "legalHoldHoldCountLimit": null,
  "concurrentUserLimit": null,
  "canChooseWorkers": null
}

If the license server is accessible, a response similar to this shortened example will be returned. The response includes details about each license type that exists on the configured licensing server.

Identify the license type that meets the needs of your job, then locate its associated short name. The short name is used during license acquisition to request a specific license type.

License Acquisition

A license is required in order to gain full access to the Nuix REST API. When you request a license, you are issued an authentication token that can then be used in all subsequent requests to the API.

Submit a request to retrieve a license and authentication token from your licensing server using the following PUT request to the /authenticatedUsers/login endpoint.

curl -L -X PUT 'http://127.0.0.1:8080/nuix-restful-service/svc/authenticatedUsers/login' \
-H 'Content-Type: application/json' \
--data-raw '{
    "username": "user1",
    "password": "password",
    "licenseShortName": "enterprise-workstation",
    "workers": 2
}'
{
  "username": "user1",
  "authToken": "49e225d7-b88d-4d1b-9cbc-296e83706a60",
  "licenseShortName": "enterprise-workstation",
  "workersGranted": 1
}

In this example, four parameters are submitted in the body of the request as JSON.

  • username: The username for an account that has access to the licensing server.
  • password: The password associated with the username.
  • licenseShortName: (Optional) The short name of the license to be retrieved.
  • workers: (Optional) The number of workers to request with the license.

Both licenseShortName and workers are optional parameters. If left undefined, the first license offered by the licensing server will be claimed. Additionally, if the selected license type supports the use of workers, a default value of one or two workers, assigned by the Nuix Engine, will also be assigned.

The response from the license acquisition request displays the issued authentication token, retrieved license type, and the number of workers that have been assigned to the license.

After obtaining the authentication token, provide it within the header of all subsequent calls to make authenticated requests to the API.

For example:

When checking the server status by calling the /about endpoint, if the request is made using an authentication token, the response will include details about the REST server instead of null values.

curl -L -X GET 'http://127.0.0.1:8080/nuix-restful-service/svc/about' \
-H 'nuix-auth-token: 49e225d7-b88d-4d1b-9cbc-296e83706a60'
{
    "server" : "http://127.0.0.1:8080/nuix-restful-service/svc",
    "serverId" : "rest-oem-server",
    "startupTime": 1602193993435,
    "nuixRestfulVersion": "8.8.0",
    "engineVersion": "8.8.0.37"
}

License Revocation

When you are finished making calls to the Nuix RESTful Service API, it is best practice to end your session. Performing this action revokes your authentication key and returns your license and any assigned workers back to the licensing server for other users to consume.

Submit a DELETE call to the /authenticatedUsers/{username)endpoint, specifying the username used to log in and your authentication token in the header of the request to revoke your license and authentication token.

curl -L -X DELETE 'http://127.0.0.1:8080/nuix-restful-service/svc/authenticatedUsers/user1' \
-H 'nuix-auth-token: 49e225d7-b88d-4d1b-9cbc-296e83706a60'
{
    "success": true
}

When this request is performed, if your session is active with running or queued functions, you will be asynchronously logged out. This default behavior allows the session to remain active until the functions have completed. At that time, the session will end, and your license will be returned.

Last modified April 22, 2021