Broker Deployment API

Use the Broker Deployment API to manage broker deployments in EMQX Cloud. This page explains how to create and manage Deployment API Keys for secure API access.

API Function

The Broker Deployment API supports deployment-level operations such as client monitoring, message publishing, authentication, and authorization.

API Reference	Deployment Type	Description
Serverless deployment API	Serverless deployment	Managing operations for client, subscription, and message publishing in Serverless deployments.
Dedicated and Dedicated Flex (v6) deployment API	Dedicated and Dedicated Flex (v6) deployment	Managing various operations in Dedicated and Dedicated Flex (v6) deployments. For v5 and v4 deployments, see v5 API and v4 API.
BYOC deployment API (same as Dedicated deployment)	BYOC (v6) deployment	Managing various operations in BYOC (v6) deployments.

Create and Manage Deployment API Keys

Deployment API Keys are used to authenticate and authorize access to the Broker 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 and Dedicated Flex Deployments

For Dedicated and Dedicated Flex 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.
   

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

   Important

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

5. Click Close on the dialog.

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.

Source and Authorization Cache Permissions (v5/v6)

In Dedicated and Dedicated Flex (v5/v6) deployments, you can select Source API and authorization cache reset permissions when creating or editing a Deployment API Key. Source API permissions allow you to manage Sources, such as Kafka Consumer Sources, through the Broker Deployment API.

Under API Permissions, expand Data Integration -> Actions (Source) to select Source API permissions. Select only the paths and HTTP methods your application needs:

Permission Path	HTTP Methods	Purpose
/api/v5/sources	GET, POST, PUT, DELETE	Manage Sources.
/api/v5/source_types	GET	List available Source types.

HTTP method permissions selected for /api/v5/sources also apply to API paths that start with /api/v5/sources, including /api/v5/sources/{id}, /api/v5/sources_summary, and /api/v5/sources_probe. Each request must use a path and method supported by the specific API operation.

For read-only access, select only the required GET permissions. Permissions for Connector, output Action, or Rule APIs do not grant access to Source APIs. Requests without the required Source API permissions can return 403.

To reset the node-level authorization cache, select the POST permission for /api/v5/authorization/node_cache/reset in the authorization permission group. This endpoint supports only POST and requires EMQX 5.10.0 or later.

Important Notice

API Keys created before these permission options became available do not automatically receive Source or authorization cache reset permissions. To use these APIs, edit the key, select the required permissions, and save the changes.

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.

   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 and Dedicated Flex): 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 and Dedicated Flex).