# Authorization via HTTP Query

The HTTP authorization method delegates access-control decisions to an external HTTP service. When a client attempts to publish or subscribe, EMQX Edge sends an HTTP request to a configured URL. If the server responds with HTTP 200, the action is allowed; otherwise, it is denied.

This method supports dynamic, fine-grained access control without restarting EMQX Edge.

## How It Works

EMQX Edge sends an HTTP request for each publish or subscribe attempt, using the method, URL, headers, and parameters you configure. The authorization server evaluates the request and returns a 200 response to allow the action, or any other status code to deny it.

**Example:** A client with ID `sensor-01` and username `sensor-user` attempts to publish to topic `home/temp`. With the following parameter configuration:

| Key | Value |
|---|---|
| `clientid` | `%c` |
| `username` | `%u` |
| `topic` | `%t` |
| `access` | `%A` |

EMQX Edge fills in the placeholders and sends:

```bash
POST http://127.0.0.1:8991/mqtt/acl
Content-Type: application/x-www-form-urlencoded

clientid=sensor-01&username=sensor-user&topic=home%2Ftemp&access=2
```

The authorization server checks its rules and responds with `HTTP 200` to allow the publish, or any other status code to deny it.

### ACL Cache TTL

To reduce the number of HTTP requests sent to the authorization server, EMQX Edge supports caching authorization results. When **ACL Cache TTL** is set to a non-zero value, the result of an authorization request is cached for the specified duration. Any subsequent request with the same parameters within that window returns the cached result immediately, without sending a new HTTP request to the server.

For example, setting ACL Cache TTL to `30s` means that once a client's subscribe or publish request is authorized, the same operation is allowed for 30 seconds without re-querying the server.

To configure ACL Cache TTL, click the **Settings** button on the **Extended** tab of the Authorization page.

Setting it to `0` (default) disables caching, so every authorization decision triggers a new HTTP request.

## Configure via Dashboard

1. In the EMQX Edge Dashboard, go to **Authorization** > **Extended**.
2. Enable **HTTP** or **HTTP Super User** using the toggle in the **Enable** column.
3. Click the edit icon in the **Actions** column to open the configuration form.
4. Fill in the **Method**, **URL**, **Headers**, and **Parameters** fields.
5. Click **Save**.

### HTTP Authorization

Configure this to authorize publish and subscribe actions:

![HTTP authorization configuration](./assets/authorization-http.png)

### HTTP Super User

Configure this to grant superuser privileges via HTTP. A super user bypasses topic-level ACL checks.

![HTTP Super User configuration](./assets/authorization-http-superuser.png)

## Configuration Reference

### Method

The HTTP request method. Accepted values: `POST` or `GET`. Default: `POST`.

### URL

The URL of your authorization server endpoint. Example: `http://127.0.0.1:8991/mqtt/acl`.

### Headers

HTTP request headers to include with each authorization request.

| Key | Description |
|---|---|
| `content-type` | Media type of the request body. Use `application/x-www-form-urlencoded` or `application/json`. |
| `accept` | Optional. You can also include headers such as `cookie` or `date`. |

### Parameters

Parameters used to construct the request body (for POST) or query string (for GET).

#### HTTP Authorization

| Key | Placeholder | Description |
|---|---|---|
| `clientid` | `%c` | MQTT Client ID |
| `username` | `%u` | Username |
| `password` | `%P` | Password |
| `access` | `%A` | Permission to be verified: `1` for subscribe, `2` for publish |
| `topic` | `%t` | The topic the client is attempting to publish to or subscribe to. |
| `ipaddr` | `%a` | Client's network IP address |
| `mountpoint` | `%m` | Mount point |
| `common` | `%C` | Common Name in client TLS certificate. Supported since EMQX Edge 1.4.0. |
| `subject` | `%d` | Subject in client TLS certificate. Supported since EMQX Edge 1.4.0. |

:::tip Note
The following keys are defined in the interface but are not yet supported in this version: `sockport`, `protocol`.
:::

#### HTTP Super User

| Key | Placeholder | Description |
|---|---|---|
| `clientid` | `%c` | MQTT Client ID |
| `username` | `%u` | Username |
| `password` | `%P` | Password |
| `access` | `%A` | Permission to be verified: `1` for subscribe, `2` for publish |
| `topic` | `%t` | The topic the client is attempting to publish to or subscribe to. |