# Manage Licenses
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 %}
## Admin workflow
1. [Add an Immuta license key to increase the number of seats or enable features](#add-an-immuta-license-key).
2. [View a list of license keys](#get-a-list-of-license-keys).
3. [View the status of license seat capacity and features](#get-the-status-of-a-license).
4. [View license usage](#get-license-usage).
5. [Delete a license key](#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.
**Required Immuta permission**: `APPLICATION_ADMIN`
#### 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.
```shell
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
```json
{
"licensekey": "licensekey0123456789abcdefghijklstring"
}
```
### Response example
```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
}
```
## View license keys
| Method | Path | Purpose |
| ------ | ------------------------------ | --------------------------------------------------------------------------------------------- |
| GET | `/admin/license` | [Get a list of all license keys](#get-a-list-of-license-keys). |
| GET | `/admin/license/licenseStatus` | [Get the status of a license key's features and seat capacity](#get-the-status-of-a-license). |
### Get a list of license keys
`GET` `/admin/license`
Get a list of all license keys.
**Required Immuta permission**: `APPLICATION_ADMIN`
#### 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.
```shell
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://www.organization.immuta.com/admin/license
```
#### Response example
```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 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.
```shell
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://www.organization.immuta.com/admin/license/licenseStatus
```
#### Response example
```json
{
"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.
**Required Immuta permission**: `APPLICATION_ADMIN`
#### 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.
```shell
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
```json
{
"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
`DELETE` `/admin/license/{licenseId}`
Delete the specified license key.
**Required Immuta permission**: `APPLICATION_ADMIN`
#### 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`.
```shell
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://www.organization.immuta.com/admin/license/1
```
### Response example
```json
{
"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
}
```
---
# Agent Instructions: 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:
```
GET https://documentation.immuta.com/2024.2/developer-guides/api-intro/immuta-v1-api/configure-your-instance-of-immuta/admin.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.