The licensing REST API lets you manage the Akula Server license.

Typically, only users configured as administrator use the licensing REST API. For more information on configuring administrator, see Define Akula Server Administrators.

The document contains the following sections on the licensing REST API:

License representation
Manage local license files

Get active license
Get installed licenses
Install a license
Create an Akula license request

Access the Verivo Licensing Server

Log in to the licensing server
Log out of the Akula licensing service
List the available licenses
Activate license

Manage licensed users

Get licensed users
Clear all licensed users
Clear a single licensed user

License representation

The response object for many of the endpoints described below contains a license definition. That definition is in the following format:

To make the endpoints easier to read, the full representation of the license is not shown in the response objects.

Manage local license files

Use the endpoints in this section to manage licenses installed locally on your Akula Server. All licenses are stored in the AKULA_HOME\licenses directory. You can use these endpoints to:

Get current active license
Get all installed licenses
Install a license
Create a request for a license

Get active license

Use a GET request to list the active license for the Akula Server. The active license is the most recently added license to the AKULA_HOME\licenses directory.

The following table describes the GET request:

Property	Value	Notes
Endpoint URL	/server/manage/licenses/active
Method	GET
Request parameters	None
Request headers	X-Ak-Session-Id: token Content-Type: application/json Accept: application/json	token is the session token returned by a successful log in. Only users who are configured as administrator users can use the licensing REST API.
Example response body	`{ "license": { "key": "license_id", "serverId": "server_id", "rules": {...} }}`	Returned as a JSON object.
Permissions	{scope}`.VIEW_LICENSE`	scope is the name of the app scope running on the Akula Server. To allow this operation on all app scopes, set scope to `server`. To set it on a specific app scope, set scope to the app scope name, which corresponds to the name of the AKZ file that defines the app scope.
Error codes	404 License key not found
Akula Version	1.0

Get installed licenses

Use a GET request to list all the installed licenses for the Akula Server. While you can have multiple installed and activated licenses, only one license can be active at a time. This request can return multiple licenses if you have multiple license files in the AKULA_HOME\licenses directory.

The following table describes the GET request:

Property	Value	Notes
Endpoint URL	/server/manage/licenses
Method	GET
Request parameters	None
Request headers	X-Ak-Session-Id: token Content-Type: application/json Accept: application/json	token is the session token returned by a successful log in. Only users who are configured as administrator users can use the licensing REST API.
Example response body	`[ { "key": 1, "serverId": server_id, "rules": { ... } }, { "key": 2, "serverId": server_id, "rules": { ... } } ]`	Returned as a JSON object.
Permissions	{scope}`.VIEW_LICENSE`	scope is the name of the app scope running on the Akula Server. To allow this operation on all app scopes, set scope to `server`. To set it on a specific app scope, set scope to the app scope name, which corresponds to the name of the AKZ file that defines the app scope.
Error codes	500 Generic license server error
Akula Version	1.0

Install a license

Use a POST request to install an Akula license file on the Akula Server. Installing the license writes a license file to the AKULA_HOME\licenses directory.

The following table describes the POST request:

Property	Value	Notes
Endpoint URL	/server/manage/license/install
Method	POST
Request parameters	The content of the license file in the body of the POST request.
Request headers	X-Ak-Session-Id: token Content-Type: application/json Accept: application/json	token is the session token returned by a successful log in. Only users who are configured as administrator users can use the licensing REST API.
Example response body	200 OK
Permissions	{scope}`.EDIT_LICENSE`	scope is the name of the app scope running on the Akula Server. To allow this operation on all app scopes, set scope to `server`. To set it on a specific app scope, set scope to the app scope name, which corresponds to the name of the AKZ file that defines the app scope.
Error codes	500 Could not write license file contents to disk 500 Could not create the license file on disk
Akula Version	1.0

Create an Akula license request

Use a GET request to create an offline license activation request. This endpoint writes to a file the information necessary to pass to the Verivo Licensing Server to activate a license.

The following table describes the GET request:

Property	Value	Notes
Endpoint URL	/server/manage/license/create
Method	GET
Request parameters	None
Request headers	X-Ak-Session-Id: token Content-Type: application/json Accept: application/json	token is the session token returned by a successful log in. Only users who are configured as administrator users can use the licensing REST API.
Example response body	The response body contains the information necessary to pass to the Verivo Licensing Server to activate a license.
Permissions	{scope}`.EDIT_LICENSE`	scope is the name of the app scope running on the Akula Server. To allow this operation on all app scopes, set scope to `server`. To set it on a specific app scope, set scope to the app scope name, which corresponds to the name of the AKZ file that defines the app scope.
Error codes	500 Generic license server error
Akula Version	1.0

Access the Verivo Licensing Server

Use the endpoints in this section to manage licenses stored on the remote Verivo Licensing Server. The Verivo Licensing Server tracks all of your licenses. You can use these endpoints to:

Log in to the Verivo Licensing Server
Log out from the Verivo Licensing Server
List the available license on the Verivo Licensing Server
Activate a license from the Verivo Licensing Server

Log in to the licensing server

Use a POST request to log in to the Akula licensing server.

The following table describes the POST request:

Property	Value	Notes
Endpoint URL	/server/manage/license/remote/auth
Method	POST
Request parameters	`{ "principal": json_principal, "secret": json_secret}`	The value of principal and secret are any valid JSON expressions including strings, numbers, or JSON objects. For example, to pass strings as principal and secret: `{ "principal":"jsmith@myco.com",` `"secret":"myPword" }` To pass a JSON object for principal: `{ "principal":{ name:"jsmith", domain:"myco.com"},` `"secret":"myPword" }`
Request headers	X-Ak-Session-Id: token Content-Type: application/json Accept: application/json	token is the session token returned by a successful log in to the Akula Server.
Example response body	`{ "token":"licensingToken", "timeout":1800000, "user": { "id":"myusername", "realm":"realmName", "info": { "firstname":"fname", "lastname":"lname", "fullname":"fullname" } }, "properties": {}, "permissions": [], "status": { "akula-server-version": "x.y.z" } }`	Returned as a JSON object. `licensingToken` is a UUID representing the session token on the Verivo Licensing Server. Pass this token to all requests to the Verivo Licensing Server. Timeout is in ms. The `user` property contains information about the user, including their id and the name of the authentication `realm`. The fields of the `info` object are all optional and are returned only if that information is available in the authentication realm. Otherwise, they are omitted from the response. As part of configuring the realm, you specify the location of this information in the realm. The `properties` property and the `permissions` property are empty. The `status` property contains the Akula Server version.
Permissions	{scope}`.VIEW_LICENSE`	scope is the name of the app scope running on the Akula Server. To allow this operation on all app scopes, set scope to `server`. To set it on a specific app scope, set scope to the app scope name, which corresponds to the name of the AKZ file that defines the app scope.
Error codes	401 License server login denied 404 License key not found 500 Generic license server error
Akula Version	1.0

Log out of the Akula licensing service

Use a DELETE request to log out of the Akula licensing service.

The following table describes the DELETE request:

Property	Value	Notes
Endpoint URL	/server/manage/license/remote/auth
Method	DELETE
Request parameters	None
Request headers	X-Ak-Session-Id: token Content-Type: application/json Accept: application/json	token is the session token returned by a successful log in to the Akula Server. `licensingToken` is a UUID representing the session token on the Verivo Licensing Server returned on a successful log in to the Licensing Server.
Example response body	200 OK
Permissions	{scope}`.VIEW_LICENSE`	scope is the name of the app scope running on the Akula Server. To allow this operation on all app scopes, set scope to `server`. To set it on a specific app scope, set scope to the app scope name, which corresponds to the name of the AKZ file that defines the app scope.
Error codes	404 License key not found 500 Generic license server error
Akula Version	1.0

List the available licenses

Use a GET request to list the available Akula licenses available to the user currently logged in to the Verivo Licensing Server.

The following table describes the GET request:

Property	Value	Notes
Endpoint URL	/server/manage/license/remote/licenses
Method	GET
Request parameters	None
Request headers	X-Ak-Session-Id: token Content-Type: application/json X-Lic-Session-Id: licensing_token Accept: application/json	token is the session token returned by a successful log in. Only users who are configured as administrator users can use the licensing REST API. `licensing_token` is a UUID representing the session token on the Verivo Licensing Server returned on a successful log in to the Licensing Server.
Example response body	`{ "licenses": [ { "key": 1, "serverId": server_id, "rules": { ... } }, { "key": 2, "serverId": server_id, "rules": { ... } } ]}`	Returned as a JSON object.
Permissions	{scope}`.VIEW_LICENSE`	scope is the name of the app scope running on the Akula Server. To allow this operation on all app scopes, set scope to `server`. To set it on a specific app scope, set scope to the app scope name, which corresponds to the name of the AKZ file that defines the app scope.
Error codes	404 License key not found
Akula Version	1.0

Activate license

Use a PUT request to activate one of your available Akula licenses. Activating a license copies the license to a file in the AKULA_HOME\licenses directory of your Akula Server.

The following table describes the PUT request:

Property	Value	Notes
Endpoint URL	/server/manage/license/remote/licenses/{license-key}	license-key corresponds to the key field of the license to activate.
Method	PUT
Request parameters	None
Request headers	X-Ak-Session-Id: token Content-Type: application/json X-Lic-Session-Id: licensing_token Accept: application/json	token is the session token returned by a successful log in. Only users who are configured as administrator users can use the licensing REST API. `licensing_token` is a UUID representing the session token on the Verivo Licensing Server returned on a successful log in to the Licensing Server.
Example response body	None
Permissions	{scope}`.EDIT_LICENSE`	scope is the name of the app scope running on the Akula Server. To allow this operation on all app scopes, set scope to `server`. To set it on a specific app scope, set scope to the app scope name, which corresponds to the name of the AKZ file that defines the app scope.
Error codes	500 Generic license server error 500 Could not write license file contents to disk 500 Could not create the license file on disk
Akula Version	1.0

Manage licensed users

Use the endpoints in this section to manage your licensed users. You can use these endpoints to:

Get licensed users
Clear all licensed users
Clear a single licensed user

Get licensed users

Use a GET request to list the licensed users for the Akula Server. A licensed user is identified by their username, or principal, and the realm in which their user credentials are stored.

The following table describes the GET request:

Property	Value	Notes
Endpoint URL	/server/manage/license/users
Method	GET
Request parameters	None
Request headers	X-Ak-Session-Id: token Content-Type: application/json Accept: application/json	token is the session token returned by a successful log in. Only users who are configured as administrator users can use the licensing REST API.
Example response body	`{ "license": { "numAuthenticatedUsers": 2, "authenticatedUsers": [ { "principal": "joe", "realm": "AD", "lastAccessDate": "2013-03-12T20:04:30.001Z" }, { "principal": "billy", "realm": "AD", "lastAccessDate": "2014-03-12T20:04:30.001Z" }] }}`	Returned as a JSON object.
Permissions	{scope}`.VIEW_LICENSE`	scope is the name of the app scope running on the Akula Server. To allow this operation on all app scopes, set scope to `server`. To set it on a specific app scope, set scope to the app scope name, which corresponds to the name of the AKZ file that defines the app scope.
Error codes	404 License key not found 404 License user not found
Akula Version	1.0

Clear all licensed users

Use a DELETE request to clear all the licensed users from the Akula Server. This reduces the number of authenticated users counted against the license to zero. Any user currently logged in will stay logged in.

The following table describes the DELETE request:

Property	Value	Notes
Endpoint URL	/server/manage/license/users
Method	DELETE
Request parameters	None
Request headers	X-Ak-Session-Id: token Content-Type: application/json Accept: application/json	token is the session token returned by a successful log in. Only users who are configured as administrator users can use the licensing REST API.
Example response body	`{ "license": { "numAuthenticatedUsers": 0 }}`	Returned as a JSON object.
Permissions	{scope}`.EDIT_LICENSE`	scope is the name of the app scope running on the Akula Server. To allow this operation on all app scopes, set scope to `server`. To set it on a specific app scope, set scope to the app scope name, which corresponds to the name of the AKZ file that defines the app scope.
Error codes	404 License key not found
Akula Version	1.0

Clear a single licensed user

Use a DELETE request to clear a licensed user from the Akula Server. This might be necessary when you reach the limit of users allowed by your license. If the removed user is currently logged in, they remain logged in.

The following table describes the DELETE request:

Property	Value	Notes
Endpoint URL	/server/manage/license/users/{realm}/{principal}	realm is the realm name containing the user's credentials. principal is the username of the user to clear.
Method	DELETE
Request parameters	None
Request headers	X-Ak-Session-Id: token Content-Type: application/json Accept: application/json	token is the session token returned by a successful log in. Only users who are configured as administrator users can use the licensing REST API.
Example response body	`{ "license": { "numAuthenticatedUsers": 2 }}`	Returned as a JSON object.
Permissions	{scope}`.EDIT_LICENSE`	scope is the name of the app scope running on the Akula Server. To allow this operation on all app scopes, set scope to `server`. To set it on a specific app scope, set scope to the app scope name, which corresponds to the name of the AKZ file that defines the app scope.
Error codes	404 License key not found LICENSE_USER_NOT_FOUND
Akula Version	1.0

Documentation

Related Topics

Labels

Documentation Downloads

All Versions

Licensing REST API

License representation

Manage local license files

Get active license

Get installed licenses

Install a license

Create an Akula license request

Access the Verivo Licensing Server

Log in to the licensing server

Log out of the Akula licensing service

List the available licenses

Activate license

Manage licensed users

Get licensed users

Clear all licensed users

Clear a single licensed user