Skip to content

You are viewing documentation for Immuta version 2023.4.

For the latest version, view our documentation for Immuta SaaS or the latest self-hosted version.

cancel

Admin API Reference Guide

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

Note

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

Endpoint

Method Path Purpose
POST /admin/license Add a license key to the Immuta instance 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 instance.

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
    },
    "nativeSqlTeradata": {
      "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

Endpoint

Method Path
GET /admin/license

Query Parameters

None.

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 instance of Immuta.

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
      },
      "nativeSqlTeradata": {
        "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

Endpoint

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

Query Parameters

None.

Response Schema

Attribute Description
activeUserCount integer The number of active users in the Immuta instance.
licenseSeats integer The total number of seats available in the license.
canAddUser boolean When true, the administrator can add user accounts to the Immuta instance.
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 instance of Immuta.

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

Endpoint

Method Path Purpose
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 instance of Immuta.

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": "kris@example.com",
      "userid": "kris@example.com",
      "iamid": "bim"
    },
    {
      "userType": "dataConsumer",
      "active": true,
      "name": "Taylor",
      "email": "taylor@example.com",
      "userid": "taylor@example.com",
      "iamid": "AzureOIDC"
    },
    {
      "userType": "dataConsumer",
      "active": true,
      "name": "Deepu",
      "email": "deepu@example.com",
      "userid": "deepu@example.com",
      "iamid": "AzureSAML"
    },
    {
      "userType": "dataConsumer",
      "active": false,
      "name": "Marc",
      "email": "marc@example.com",
      "userid": "marc@example.com",
      "iamid": "OIDC"
    },
    {
      "userType": "dataConsumer",
      "active": true,
      "name": "Mandeep",
      "email": "mandeep@example.com",
      "userid": "mandeep@example.com",
      "iamid": "SAML"
    }
  ]
}

Delete a license key

Endpoint

Method Path Purpose
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
    },
    "nativeSqlTeradata": {
      "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
}