• Home
  • Getting Started
  • Documentation
  • API References
  • Downloads
  • Support
Verivo
DevCenter
  • Welcome, Anonymous
  • |
  • Log in
  1. 2.5 Documentation
  2. REST API Reference
  3. Licensing REST API
Printable version    

Documentation

Related Topics

Page: Licensing REST API
Page: REST API Permissions
Page: Client Action REST API
Page: Using the REST API
Page: App Scope Management REST API
Page: Client Rules REST API
Page: Push REST API
Page: App Property Management REST API
Page: Logging REST API
Page: Realms REST API
Page: Authentication REST API
  

Labels

  • licensing
  • rest_api

Documentation Downloads

  • Installing and Configuring Akula
  • Building Akula Apps
  • Release Notes

All Versions

Latest Official Version (2.5)
Version 3.0 Beta
Version 2.5
Version 2.1
Version 2.0
Version 1.5
Version 1.0.1
Your Rating: Thanks for voting! Please Wait Please Wait Results: PatheticBadOKGoodOutstanding! 1 rates
Client Rules REST API      Logging REST API

Licensing REST API

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:

PropertyValueNotes
Endpoint URL/server/manage/licenses/active 
MethodGET 
Request parametersNone 
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 Version1.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:

PropertyValueNotes
Endpoint URL/server/manage/licenses 
MethodGET 
Request parametersNone 
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 Version1.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:

PropertyValueNotes
Endpoint URL/server/manage/license/install 
MethodPOST 
Request parametersThe 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 Version1.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:

PropertyValueNotes
Endpoint URL/server/manage/license/create
 
MethodGET 
Request parametersNone 
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 Version1.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:

PropertyValueNotes
Endpoint URL/server/manage/license/remote/auth 
MethodPOST 
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 Version1.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:

PropertyValueNotes
Endpoint URL/server/manage/license/remote/auth 
MethodDELETE 
Request parametersNone 
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 Version1.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:

PropertyValueNotes
Endpoint URL/server/manage/license/remote/licenses 
MethodGET 
Request parametersNone 
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 Version1.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:

PropertyValueNotes
Endpoint URL/server/manage/license/remote/licenses/{license-key}license-key corresponds to the key field of the license to activate.
MethodPUT 
Request parametersNone 
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 Version1.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:

PropertyValueNotes
Endpoint URL/server/manage/license/users 
MethodGET 
Request parametersNone 
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 Version1.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:

PropertyValueNotes
Endpoint URL/server/manage/license/users 
MethodDELETE 
Request parametersNone 
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 Version1.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:

PropertyValueNotes
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.

MethodDELETE 
Request parametersNone 
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 Version1.0 
                                               
 
Client Rules REST API      Logging REST API
  • Last edited by rcrouse@verivo.com on 2014-10-17 14:50:04.0

  • Privacy Policy | Legal Information
    © Copyright 2014, Verivo Software, Inc. All Rights Reserved.