# Manage API Keys

API keys allow users (and system integrations) to authenticate to the Immuta API. The identity manager API includes endpoints to create, list, and delete API keys.

## Endpoints and methods

| Method     | Endpoint                                                                                                    | Description                                   |
| ---------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| **POST**   | [<mark style="color:blue;">`/apikey`</mark>](#post-apikey)                                                  | Creates an API key for the current user       |
| **POST**   | [<mark style="color:blue;">`/apikey/system`</mark>](#post-apikey-system)                                    | Creates (or returns) a system API key (admin) |
| **GET**    | [<mark style="color:blue;">`/iam/{iamid}/user/{userid}/apikeys`</mark>](#get-iam-iamid-user-userid-apikeys) | Lists API key metadata for a user             |
| **DELETE** | [<mark style="color:blue;">`/apikey/{keyid}`</mark>](#delete-apikey-keyid)                                  | Deletes an API key (current user only)        |
| **DELETE** | [<mark style="color:blue;">`/apikey/system/{keyid}`</mark>](#delete-apikey-system-keyid)                    | Deletes a system API key (admin)              |

## <mark style="color:green;">`POST`</mark> `/apikey`

Create a new API key for the currently authenticated user.

```bash
curl -X 'POST' \
  'https://your.immuta.url.com/apikey' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <access_token>' \
  -d '{
  "projectId": 123,
  "name": "My CLI key"
  }'
```

#### Body parameters

| Parameter               | Description                                                                                                                                                           | Required or optional | Default values | Accepted values  |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | -------------- | ---------------- |
| **projectId** `integer` | The project to assign this API key to. If omitted or set to `null`, the request will use the user's current project and set the API key context to `CURRENT_PROJECT`. | Optional             | `null`         | -                |
| **name** `string`       | The name to associate with this API key.                                                                                                                              | Optional             | `null`         | Max length `254` |

#### Response

```json
{
  "apikey": "your-new-api-key",
  "keyid": 456,
  "project": 123,
  "name": "My CLI key",
  "context": "CURRENT_PROJECT"
}
```

#### Error responses

* **400**: User is not a member of the project specified; acknowledgement required; or other invalid request state.
* **404**: Project not found.

### <mark style="color:green;">`POST`</mark> `/apikey/system`

Create an API key for the system. Currently this endpoint can only be used to create the API key for Trino connections.

**Required Immuta permission**: `APPLICATION_ADMIN`

{% hint style="info" %}
**Idempotent behavior**

If a system API key with the given `name` already exists and it matches the same `connectionKey` and `scopes`, the endpoint will return the existing key. To rotate the key, set `regenerate` to `true`.
{% endhint %}

```bash
curl -X 'POST' \
  'https://your.immuta.url.com/apikey/system' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <admin_access_token>' \
  -d '{
  "name": "trino-connection-1",
  "scopes": ["plugin:trino"],
  "connectionKey": "connection-abc123",
  "regenerate": false
  }'
```

#### Body parameters

| Parameter                  | Description                                                                                                                                                                                                         | Required or optional | Default values | Accepted values    |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | -------------- | ------------------ |
| **name** `string`          | The unique name to associate with the system API key.                                                                                                                                                               | Required             | -              | -                  |
| **scopes** `array`         | The scope of the API key. Must be non-empty and valid. Currently, the only supported scope is `["plugin:trino"]`                                                                                                    | Required             | -              | `["plugin:trino"]` |
| **connectionKey** `string` | The connection key for the connection the API key will be used with.                                                                                                                                                | Required             | -              | -                  |
| **regenerate** `boolean`   | <p>If <code>true</code>, a new API key will be created even if there is already an API key associated with the same connection and scope.<br><br>If <code>false</code>, it will return the existing key.</p><p></p> | Optional             | `false`        | `true` or `false`  |

#### Response

```json
{
  "apikey": "your-api-key",
  "keyid": 987,
  "name": "trino-connection-1"
}
```

#### Error responses

* **400**: Connection key not found, scopes invalid, or a key with the same name exists for a different connection or scope.

### <mark style="color:green;">`GET`</mark> `/iam/{iamid}/user/{userid}/apikeys`

Retrieve metadata for all the user's API keys.

**Requirement**: You must own the API key or have the `USER_ADMIN` permission

```bash
curl -X 'GET' \
  'https://your.immuta.url.com/iam/<iamid>/user/<userid>/apikeys' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <access_token>'
```

#### Path parameters

| Parameter           | Description                     |
| ------------------- | ------------------------------- |
| **iamid** `string`  | The IAM identifier.             |
| **userid** `string` | The user identifier in the IAM. |

#### Response

Returns an array of API key metadata objects.

```json
[
  {
    "keyid": 456,
    "created": "2025-01-15T18:22:10.000Z",
    "project": null,
    "lastUsed": null,
    "name": "My CLI key",
    "context": "CURRENT_PROJECT"
  }
]
```

### <mark style="color:green;">`DELETE`</mark> `/apikey/{keyid}`

Delete an API key owned by the current user. This also deletes all auth tokens derived from that API key.

```bash
curl -X 'DELETE' \
  'https://your.immuta.url.com/apikey/456' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <access_token>'
```

#### Path parameter

| Parameter           | Description |
| ------------------- | ----------- |
| **keyid** `integer` | API key ID. |

#### Response

```json
{
  "revokedTokens": 12
}
```

#### Error responses

* **403**: You may not delete another user's API key.
* **404**: API key not found or no keys deleted.

### <mark style="color:green;">`DELETE`</mark> `/apikey/system/{keyid}`

Delete a system API key.

**Required Immuta permission**: `APPLICATION_ADMIN`

```bash
curl -X 'DELETE' \
  'https://your.immuta.url.com/apikey/system/987' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <admin_access_token>'
```

#### Path parameter

| Parameter           | Description        |
| ------------------- | ------------------ |
| **keyid** `integer` | System API key ID. |

#### Response

```json
{
  "revokedKeys": 1
}
```

#### Error responses

* **404**: System API key not found.