> For the complete documentation index, see [llms.txt](https://documentation.immuta.com/saas/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.immuta.com/saas/developer-guides/api-intro/immuta-v1-api/configure-your-instance-of-immuta/admin.md). # Manage Licenses Understand the parameters and response schema of the admin endpoints This page outlines the `admin` endpoint, which allows you to manage and review licenses in Immuta. {% hint style="info" %} Additional fields may be included in some responses you receive; however, these attributes are for internal purposes and are therefore undocumented. {% endhint %} ## Endpoints and methods | Method | Endpoint | Description | | ------ | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | | POST | [`/admin/license`](#post-admin-license) | Add a license key to the Immuta tenant to increase the number of seats or enable features. | | GET | [`/admin/license`](#get-admin-license) | Get a list of all license keys. | | GET | [`/admin/license/licenseStatus`](#get-admin-license-licensestatus) | Get the status of a license key's features and seat capacity. | | GET | [`/admin/license/usage`](#get-admin-license-usage) | Get information about the license consumption for your tenant. | | DELETE | [`/admin/license/{licenseId}`](#delete-admin-license-licenseid) | Delete the specified license key. | ## `POST` `/admin/license` Add a license key to the Immuta tenant to increase the number of seats or enable features. **Required Immuta permission**: `APPLICATION_ADMIN` ```bash curl \ --request POST \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ --data @example-payload.json \ https://www.organization.immuta.com/admin/license ``` **Payload** ```json { "licensekey": "licensekey0123456789abcdefghijklstring" } ``` ### Body parameter | Parameter | Description | Required | | ----------------------- | ---------------- | -------- | | **licenseKey** `string` | The license key. | **Yes** | ### Response Returns a [license object](#license-object-attributes). ```json { "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 } ``` ## `GET` `/admin/license` Get a list of all license keys. **Required Immuta permission**: `APPLICATION_ADMIN` ```bash curl \ --request GET \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ https://www.organization.immuta.com/admin/license ``` ### Response Returns a property that contains an array of [license objects](#license-object-attributes). ```json [ { "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` `/admin/license/licenseStatus` Get the status of a license key's features and seat capacity. ```bash curl \ --request GET \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ https://www.organization.immuta.com/admin/license/licenseStatus ``` ### Response ```json { "activeUserCount": 1, "licenseSeats": 20, "canAddUser": true, "hardSeats": 20 } ``` #### Response attributes | 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. | ## `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. **Required Immuta permission**: `APPLICATION_ADMIN` ```bash curl \ --request GET \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ https://www.organization.immuta.com/admin/license/usage?offset=0&size=5 ``` #### Query parameters | Parameter | Description | Required or optional | Default values | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | -------------- | | **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`. | Optional | `0` | | **size** `integer` | The number of user records to return. | Optional | `10` | ### Response ```json { "summary": { "dataConsumers": { "totalCount": 35, "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" } ] } ``` #### Response attributes | Attribute | Description | | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **users** `array[]` | An array of user records. Disabled users are excluded from any of the counts returned in the response, as disabled users do not count against license consumption. | | users.**userType** `string` | The type of user: `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:

| | **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**](#user-content-fn-1)[^1]. | | 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:

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

| | 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:

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

| ## `DELETE` `/admin/license/{licenseId}` Delete the specified license key. **Required Immuta permission**: `APPLICATION_ADMIN` ```bash curl \ --request DELETE \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ https://www.organization.immuta.com/admin/license/1 ``` #### Path parameter | Parameter | Description | Required or optional | | ----------------------- | --------------------------------------------- | -------------------- | | **licenseId** `integer` | The ID of the license key you want to delete. | Required | ### Response Returns a [license object](#license-object-attributes) for the deleted license. ```yaml { "id": 1, "licenseKey": "", "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 } ``` ## License object attributes | Attribute | Description | | --------------------------- | ---------------------------------------------------------------- | | **licenseKey** `string` | The license key. | | **id** `integer` | The ID of the license. | | **uuid** `string` | The unique universal identifier of the license. | | **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. | [^1]: Enabled users are counted as policy owners if they meet one of the following criteria: * User has one of the following **global permissions** (directly assigned or via group-based permission): `CREATE_DATA_SOURCE`, `GOVERNANCE`, `USER_ADMIN`, `APPLICATION_ADMIN`, `IMPERSONATE_USER`, `PROJECT_MANAGEMENT`, `FETCH_POLICY_INFO`, or `AUDIT` * User has the `Manage Policies` **domain-level permissions** on at least one domain (directly assigned or via group-based permission) * User has one of the following **data source level permissions** on at least one data source (directly assigned or via group-based permission): `owner` or `expert` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://documentation.immuta.com/saas/developer-guides/api-intro/immuta-v1-api/configure-your-instance-of-immuta/admin.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.