# Deployment API

This section provides an overview of the EMQX Deployment API and explains how to securely create and manage Deployment API Keys.

## API Function

EMQX Deployment API manages the functionalities at the deployment level, such as client monitoring, message publishing, authentication, authorization, and so on.

| API Reference                                                | Deployment Type                              | Description                                                  |
| ------------------------------------------------------------ | -------------------------------------------- | ------------------------------------------------------------ |
| [Serverless deployment API](./serverless.md)                 | Serverless deployment                        | Managing operations for client, subscription, and message publishing in Serverless deployments. |
| [Dedicated and Dedicated Flex deployment API](https://docs.emqx.com/en/cloud/latest/api/dedicated.html) | Dedicated and Dedicated Flex (v5) deployment | Managing various operations in Dedicated (v5) deployments. If you need to access the v4 Deployment API, see [v4 API](https://docs.emqx.com/en/cloud/v4/api/dedicated.html). |
| [BYOC deployment API](https://docs.emqx.com/en/cloud/latest/api/dedicated.html) (same as Dedicated deployment) | BYOC (v5) deployment                         | Managing various operations in BYOC (v5) deployments.        |


## Create and Manage Deployment API Keys

Deployment API Keys are used to authenticate and authorize access to the EMQX Deployment API. The method for creating and managing API Keys differs based on the type and version of the deployment.

### Create API Keys in Dedicated (v4/v5) Deployments

For Dedicated (v4) and Dedicated (v5) deployments, you can add custom notes and assign fine-grained access permissions to each API Key.

1. Go to the **Deployment Overview** page of the target deployment.

2. In the **Deployment API Key** section, click **+ New API Key**.

3. In the dialog that appears:

   - **Note** (optional): Add a description to identify the key’s purpose and scope.
   - **API Permissions**:
     - Select HTTP methods (`GET`, `POST`, `PUT`, `DELETE`) as needed.
     - Filter or search for specific API endpoints.
     - Use category-level checkboxes to select entire categories or individual APIs.

   <img src="./_assets/new_api_key_dedicatedv5.png" alt="new_api_key_dedicatedv5" style="zoom:67%;" />

4. After clicking **Confirm**, a dialog displays the generated **App ID** and **App Secret**.

   ::: tip Important

   The App Secret is shown only once during key creation. Make sure to store it securely, as it cannot be retrieved later.

   :::

6. Click **Close** on the dialog.

::: tip Note

Dedicated (v4) API Keys created before the permissions feature was launched have full access by default, with a blank note and no creation time shown in the list. It is recommended to delete old API Keys and recreate them to gain full permission control and creation time records.

:::

### Create API Keys in Serverless Deployments

For Serverless deployments, API Keys are automatically generated with full access. Serverless deployments do not support permission configuration or note fields.

1. Go to the **Deployment Overview** page of the target Serverless deployment.

2. In the **Deployment API Key** section, click **+ New API Key**.

3. The system will automatically generate an **App ID** and **App Secret**, which are displayed in a confirmation dialog.

   ::: tip Important

   The App Secret is shown only once during key creation. Make sure to store it securely, as it cannot be retrieved later.

   :::

4. Click **Close** on the dialog.

### Manage API Keys

- **Edit** (Dedicated v5 and v4): Update the note or modify assigned API permissions.

- **Delete**: Delete an API Key to revoke access immediately.

- **View Access**: Expand a key entry to view its assigned permissions (Dedicated v5 and v4).

  ![view_api_key](./_assets/view_api_key.png)