# 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>](/saas/developer-guides/api-intro/immuta-v1-api/configure-your-instance-of-immuta/bim.md#view-a-users-api-keys) | 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.

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

## <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.


---

# 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/saas/developer-guides/api-intro/immuta-v1-api/configure-your-instance-of-immuta/manage-api-keys.md?ask=<question>
```

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.