Manage Licenses

Admin API reference guide

This page outlines the admin endpoint, which allows you to manage and review licenses in Immuta.

Additional fields may be included in some responses you receive; however, these attributes are for internal purposes and are therefore undocumented.

Admin workflow

1. Add an Immuta license key to increase the number of seats or enable features.

2. View a list of license keys.

3. View the status of license seat capacity and features.

4. View license usage.

5. Delete a license key.

Add an Immuta license key

POST /admin/license

Add a license key to the Immuta tenant to increase the number of seats or enable features.

Query parameters

Parameter	Description	Required
licenseKey	string The license key, as a payload.	Yes

Response schema

Attribute	Description
licenseKey	string The license key.
id	integer The ID of the license.
uuid	string The unique universal identifier.
features	array The features included in the license.
handlers	array The data handlers included in the license.
expires	timestamp The date the license expires.
seats	integer The number of user seats available.
createdAt	timestamp The date the license key was generated.
notice	string This notice appears on the login page.
noticeOnExpire	string This notice appears on the login page after the license expires.

Request example

This example request adds a license key (saved in the example-payload.json file) to the Immuta tenant.

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8"
    --data @example-payload.json \
    https://www.organization.immuta.com/admin/license

Request payload example

{
  "licensekey": "licensekey0123456789abcdefghijklstring"
}

Response example

{
  "id": 1,
  "licenseKey": "licensekey0123456789abcdefghijklstring",
  "seats": 20,
  "softSeats": 0,
  "expires": "2022-09-09T00:00:00.000Z",
  "uuid": "4ceaf808-the-u-u--id4a753fc5a",
  "deleted": false,
  "invalidated": false,
  "features": {
    "FPE": {
      "enabled": true
    }
  },
  "handlers": {},
  "hardExpiration": false,
  "renewalToken": null,
  "notice": null,
  "noticeOnExpire": null,
  "classifyUsername": null,
  "classifyToken": null,
  "createdAt": "2021-09-09T13:47:02.473Z",
  "updatedAt": "2021-10-07T17:55:54.806Z",
  "expired": false
}

View license keys

Method	Path	Purpose
GET	/admin/license	Get a list of all license keys.
GET	/admin/license/licenseStatus	Get the status of a license key's features and seat capacity.

Get a list of license keys

GET /admin/license

Get a list of all license keys.

Response schema

Attribute	Description
id	integer The ID of the license.
uuid	string The unique universal identifier.
features	array The features included in the license.
handlers	array The data handlers included in the license.
expires	timestamp The date the license expires.
seats	integer The number of user seats available.
createdAt	timestamp The date the license key was generated.
notice	string This notice appears on the login page.
noticeOnExpire	string This notice appears on the login page after the license expires.

Request example

This example request gets the license key for the https://www.organization.immuta.com Immuta tenant.

curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://www.organization.immuta.com/admin/license

Response example

[
  {
    "id": 1,
    "uuid": "4cthe808-uniq-uec9-univ-ersal753fcid",
    "features": {
      "FPE": {
        "enabled": true
      }
    },
    "handlers": {},
    "expires": "2022-09-09T00:00:00.000Z",
    "seats": 20,
    "createdAt": "2021-09-09T13:47:02.473Z",
    "notice": null,
    "noticeOnExpire": null
  }
]

Get the status of a license

GET /admin/license/licenseStatus

Get the status of a license key's features and seat capacity.

Response schema

Attribute	Description
activeUserCount	integer The number of active users in the Immuta tenant.
licenseSeats	integer The total number of seats available in the license.
canAddUser	boolean When true, the administrator can add user accounts to the Immuta tenant.
hardSeats	integer The number of licensed seats available.

Request example

This example request gets the number of seats and active users for the license key associated with the https://www.organization.immuta.com Immuta tenant.

curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://www.organization.immuta.com/admin/license/licenseStatus

Response example

{
  "activeUserCount": 1,
  "licenseSeats": 20,
  "canAddUser": true,
  "hardSeats": 20
}

Get license usage

GET /admin/license/usage

Get the license usage summary. This endpoint returns a summary of the number of active and inactive users and a list of users.

Query parameters

Parameter	Description	Required
offset	integer The start index of the records to return. You can combine the offset and size parameters to return a specific set of user records. For example, to return the second and third user records in the response, you would set offset=1 and size=2. The default start index is 0.	No
size	integer The number of user records to return. The default size is 10.	No

Response schema

Attribute	Description
users	array[] An array of user records.
users.userType	string The type of user. Value can be dataConsumer or policyOwner.
users.name	string The name of the user.
users.email	string The user's email address.
users.iamid	string The IAM the user belongs to.
users.userid	string The user's username.
users.active	boolean If true, the user is active. This is determined by whether Immuta has tracked any activity by the user in the last year.
summary	object The summary of license usage that covers all users, not just the subset returned by a call to this endpoint.
summary.dataConsumers	array Includes a summary of the dataConsumers type.
summary.dataConsumers.totalCount	integer The total number of users of this type known to Immuta.
summary.dataConsumers.activeCount	integer The number of active data consumers known to Immuta, determined by whether Immuta has tracked any activity by the user in the last year. Minimum value is 0.
summary.dataConsumers.inactiveCount	integer The number of inactive data consumers known to Immuta, determined by whether Immuta has tracked any activity by the user in the last year. Minimum value is 0.
summary.policyOwners	object Includes a summary of the policyOwners type.
summary.policyOwners.totalCount	integer The total number of users of this type known to Immuta.

Request example

This request gets the license usage for 5 users in the https://www.organization.immuta.com Immuta tenant.

curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://www.organization.immuta.com/admin/license/usage?offset=0&size=5

Response example

{
  "summary": {
    "dataConsumers": {
      "totalCount": 25,
      "activeCount": 10,
      "inactiveCount": 25
    },
    "policyOwners": {
      "totalCount": 1
    }
  },
  "users": [{
      "userType": "policyOwner",
      "name": "Kris",
      "email": "[email protected]",
      "userid": "[email protected]",
      "iamid": "bim"
    },
    {
      "userType": "dataConsumer",
      "active": true,
      "name": "Taylor",
      "email": "[email protected]",
      "userid": "[email protected]",
      "iamid": "AzureOIDC"
    },
    {
      "userType": "dataConsumer",
      "active": true,
      "name": "Deepu",
      "email": "[email protected]",
      "userid": "[email protected]",
      "iamid": "AzureSAML"
    },
    {
      "userType": "dataConsumer",
      "active": false,
      "name": "Marc",
      "email": "[email protected]",
      "userid": "[email protected]",
      "iamid": "OIDC"
    },
    {
      "userType": "dataConsumer",
      "active": true,
      "name": "Mandeep",
      "email": "[email protected]",
      "userid": "[email protected]",
      "iamid": "SAML"
    }
  ]
}

Delete a license key

DELETE /admin/license/{licenseId}

Delete the specified license key.

Query parameters

Parameter	Description	Required
licenseId	integer The ID of the license key you want to delete.	Yes

Response schema

Attribute	Description
id	integer The license key ID.
licenseKey	string The license key.
seats	integer The number of seats in the license.
softSeats	integer The number of users that can be added beyond seats without access being blocked.
expires	timestamp The date the license expires.
uuid	string The unique universal identifier.
deleted	boolean If true, the license key has been deleted.
features	array The features included in the license.
handlers	array The data handlers included in the license.
hardExpiration	boolean When true, all data access is blocked when the license expires.
notice	string This notice appears on the login page.
noticeOnExpire	string This notice appears on the login page after the license expires.
createdAt	timestamp The date the license key was generated.
updatedAt	timestamp The date the license key was deleted.
hardDelete	boolean If true, the license key cannot be re-added after it is deleted.
expired	boolean If true, the license has expired.

Request example

This example request deletes the license key with the ID 1.

curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://www.organization.immuta.com/admin/license/1

Response example

{
  "id": 1,
  "licenseKey": "<your-license-key>",
  "seats": 20,
  "softSeats": 0,
  "expires": "2022-09-09T00:00:00.000Z",
  "uuid": "4cthe808-uniq-uec9-univ-ersal753fcid",
  "deleted": true,
  "invalidated": false,
  "features": {
    "FPE": {
      "enabled": true
    }
  },
  "handlers": {},
  "hardExpiration": false,
  "notice": null,
  "noticeOnExpire": null,
  "createdAt": "2021-09-09T13:47:02.473Z",
  "updatedAt": "2021-09-13T16:53:39.280Z",
  "hardDelete": false,
  "expired": false
}