Manage Licenses with REST

Learn how to acquire and manage Nuix licenses.

4 minute read

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. You can use this token to make authenticated API calls during your session.

Note: Based on the configuration of your installation of Nuix RESTful Service, your authentication token may expire if your session becomes inactive. If this occurs, a new token must be retrieved using the steps within this topic.

In this topic, you’ll learn how to:

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

Check license availability

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

To check which Nuix license types are available on your NMS instance, use 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.

Acquire a license

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.

Note: Workers are a consumable entity within your environment like licenses. If no workers are available at the time that a license is requested, no workers will be assigned. Similarly, if many workers are requested, but only a few are available, a subset of the total requested workers equal to the number of available workers will 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-server",
    "startupTime": 1602193993435,
    "nuixRestfulVersion": "9.10.22",
    "engineVersion": "${nuix-engine}"
}

Release your license

When you finish 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 request header.

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
}

By default, if your session is active with running or queued functions when you perform this request, you will be asynchronously logged out. This allows the session to remain active until the functions have completed. After the functions have completed, the session will end and your license will be returned.

Feedback

Was this page helpful?

Thank you for your feedback.