Book a demo

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 information about the license consumption for your tenant. This endpoint returns a summary of user counts by license type, as well as a list of all individual users with the license type they currently use.

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

Disabled users are excluded from any of the counts returned in the response, as disabled users do not count against license consumption.

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 Only tracked for user type dataConsumers. If true, this means the user has run at least one query in the past year (rolling basis) in one of the following platforms that support query audit:

  • Snowflake

  • Databricks Unity Catalog

  • Databricks Spark

  • Starburst (Trino)

summary

object The summary of license usage that covers all enabled users.

summary.dataConsumers.totalCount

integer The total number of enabled users that do not match the logic for summary.policyOwners.totalCount.

summary.dataConsumers.activeCount

integer The number of users registered in Immuta that have run at least one query in the past year (rolling basis) in one of the following platforms that support query audit:

  • Snowflake

  • Databricks Unity Catalog

  • Databricks Spark

  • Starburst (Trino)

The dataConsumers.activeCount will always be 0 for customers in either of the following scenarios:

  • Using Immuta exclusively with technologies where query audit is not supported

  • Using Immuta with technologies where query audit is supported, but query audit has been disabled

summary.dataConsumers.inactiveCount

integer The number of inactive data consumers. This value is calculated by subtracting summary.dataConsumers.activeCount from summary.dataConsumers.totalCount.

summary.policyOwners.totalCount

integer The total number of policy owners. Enabled users are counted as policy owners if they meet any of the following criteria:

  • User has one of the following global permissions (directly assigned or via group-based assignment): CREATE_DATA_SOURCE, GOVERNANCE, USER_ADMIN, APPLICATION_ADMIN, IMPERSONATE_USER, PROJECT_MANAGEMENT, FETCH_POLICY_INFO, or AUDIT

  • User has the Manage Policies domain-level permission on at least one domain (directly assigned or via group-based assignment)

  • User has one of the following data source roles on at least one data source (directly assigned or via group-based assignment): owner or expert

All enabled users that do not match the logic for policyOwners are counted as dataConsumers instead.

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": 35,
      "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
}
PreviousManage IAMsNextManage Notifications

Last updated

Was this helpful?