Skip to content

Access Control Management API

This API documentation provides various operation information related to Access Control (ACL) management, including creating, viewing, updating, and deleting ACL rules.

Create ACL Rule Based on clientid

URI

POST /acl

Request Message

NameTypeDescription
clientidStringclientid
topicStringTopic
actionStringAction: sub, pub, pubsub
accessStringIf allowed: allow, deny

Response Message

NameTypeDescription
codeInteger0
dataObjectRule Object
data.topicStringTopic
data.resultStringResult
data.clientidStringclientid
data.actionStringAction
data.accessStringIf allowed

Request Example

bash
curl -u app_id:app_secret -X POST -d '{"clientid": "client1","topic": "a/b","action": "sub","access": "allow"}' {api}/acl

Response Example

JSON
{
  "data": {
    "topic": "a/b",
    "result": "ok",
    "clientid": "client1",
    "action": "sub",
    "access": "allow"
  },
  "code": 0
}

Create ACL Rule Based on username

URI

POST /acl

Request Message

NameTypeDescription
usernameStringusername
topicStringTopic
actionStringAction: sub, pub, pubsub
accessStringIf allowed: allow, deny

Response Message

NameTypeDescription
codeInteger0
dataObjectRule Object
data.topicStringTopic
data.resultStringResult
data.usernameStringusername
data.actionStringAction
data.accessStringIf allowed

Request Example

bash
curl -u app_id:app_secret -X POST -d '{"username": "user1","topic": "a/b","action": "sub","access": "allow"}' {api}/acl

Response Example

JSON
{
  "data": {
    "username": "user1", 
    "topic": "a/b", 
    "result": "ok", 
    "action": "sub", 
    "access": "allow"
  }, 
  "code": 0
}

Create ACL Rule Based on All

URI

POST /acl

Request Message

NameTypeDescription
topicStringTopic
actionStringAction: sub, pub, pubsub
accessStringIf allowed: allow, deny

Response Message

NameTypeDescription
codeInteger0
dataObjectRule Object
data.topicStringTopic
data.resultStringResult
data.allString$all
data.actionStringAction
data.accessStringIf allowed

Request Example

bash
curl -u app_id:app_secret -X POST -d '{"topic": "a/b","action": "pub","access": "allow"}' {api}/acl

Response Example

JSON
{
  "data": {
    "topic": "a/b",
    "result": "ok",
    "all": "$all",
    "action": "pub",
    "access": "allow"
  },
  "code": 0
}

Batch Add ACL Rule

URI

POST /acl

Request Message

NameTypeDescription
[0].clientidStringclientid
[0].topicStringTopic
[0].actionStringAction: sub, pub, pubsub
[0].accessStringIf allowed: allow, deny
[1].usernameStringusername
[1].topicStringTopic
[1].actionStringAction: sub, pub, pubsub
[1].accessStringIf allowed: allow, deny
[2].topicStringTopic
[2].actionStringAction: sub, pub, pubsub
[2].accessStringIf allowed: allow, deny

Response Message

NameTypeDescription
codeInteger0
dataObjectRule Object
[0].clientidStringclientid
[0].topicStringTopic
[0].actionStringAction: sub, pub, pubsub
[0].accessStringIf allowed: allow, deny
[0].resultStringResult
[1].usernameStringusername
[1].topicStringTopic
[1].actionStringAction: sub, pub, pubsub
[1].accessStringIf allowed: allow, deny
[1].resultStringResult
[2].topicStringTopic
[2].actionStringAction: sub, pub, pubsub
[2].accessStringIf allowed: allow, deny
[2].allString$All
[2].resultStringResult

Request Example

bash
curl -u app_id:app_secret -X POST -d '[{"clientid": "emqx_c_1","topic": "topic/A","action": "pub","access": "allow"},{"username": "emqx_u_1","topic": "topic/A","action": "sub","access": "allow"},{"topic": "topic/+","action": "pubsub","access": "deny"}]' {api}/acl

Response Example

JSON
{
  "data": [
    {
      "topic": "topic/+",
      "result": "ok",
      "all": "$all",
      "action": "pubsub",
      "access": "deny"
    },
    {
      "username": "emqx_u_1",
      "topic": "topic/A",
      "result": "ok",
      "action": "sub",
      "access": "allow"
    },
    {
      "topic": "topic/A",
      "result": "ok",
      "clientid": "emqx_c_1",
      "action": "pub",
      "access": "allow"
    }
  ],
  "code": 0
}

View ACL Rules by clientid

URI

GET /acl/clientid

Request Message

None.

Response Message

NameTypeDescription
codeInteger0
dataArray of ObjectsAll the authentication information
data[].topicStringTopic
data[].resultStringResult
data[].clientidStringclientid
data[].actionStringAction
data[].accessStringIf allowed
metaObjectPaging information
meta.pageIntegerPage number
meta.limitIntegerNumber of data items displayed per page
meta.countIntegerTotal number of data

Request Example

bash
curl -u app_id:app_secret -X GET {api}/acl/clientid

Response Example

JSON
{
  "meta": {
    "page": 1,
    "limit": 10,
    "count": 1
  },
  "data": [
    {
      "topic": "topic/A",
      "clientid": "emqx_c_1",
      "action": "pub",
      "access": "allow"
    }
  ],
  "code": 0
}

View ACL Rules by username

URI

GET /acl/username

Request Message

None.

Response Message

NameTypeDescription
codeInteger0
dataArray of ObjectsAll the authentication information
data[].topicStringTopic
data[].resultStringResult
data[].usernameStringusername
data[].actionStringAction
data[].accessStringIf allowed
metaObjectPaging information
meta.pageIntegerPage number
meta.limitIntegerNumber of data items displayed per page
meta.countIntegerTotal number of data

Request Example

bash
curl -u app_id:app_secret -X GET {api}/acl/username

Response Example

JSON
{
  "meta": {
    "page": 1,
    "limit": 10,
    "count": 1
  },
  "data": [
    {
      "username": "emqx_u_1",
      "topic": "topic/A",
      "action": "sub",
      "access": "allow"
    }
  ],
  "code": 0
}

View ACL Rules Based on ALL

URI

GET /acl/$all

Request Message

None.

Response Message

NameTypeDescription
codeInteger0
dataArray of ObjectsAll the authentication information
data[].topicStringTopic
data[].resultStringResult
data[].allString$all
data[].actionStringAction
data[].accessStringIf allowed
metaObjectPaging information
meta.pageIntegerPage number
meta.limitIntegerNumber of data items displayed per page
meta.countIntegerTotal number of data

Request Example

bash
curl -u app_id:app_secret -X GET {api}/acl/\$all

Response Example

JSON
{
  "meta": {
    "page": 1,
    "limit": 10,
    "count": 1
  },
  "data": [
    {
      "topic": "topic/A",
      "all": "$all",
      "action": "sub",
      "access": "allow"
    }
  ],
  "code": 0
}

View ACL Rules by Specified clientid

URI

GET /acl/clientid/{clientid}

Parameter

NameTypeDescription
clientidStringClient ID

Request Message

None.

Response Message

NameTypeDescription
codeInteger0
dataArray of ObjectsAll the authentication information
data[].topicStringTopic
data[].clientidStringclientid
data[].actionStringAction
data[].accessStringIf allowed

Request Example

bash
curl -u app_id:app_secret -X GET {api}/acl/clientid/emqx_c_1

Response Example

JSON
{
  "data": [
    {
      "topic": "topic/A",
      "clientid": "emqx_c_1",
      "action": "pub",
      "access": "allow"
    }
  ],
  "code": 0
}

View ACL Rules by Specified username

URI

GET /acl/username/{username}

Parameter

NameTypeDescription
usernameStringusername

Request Message

None.

Response Message

NameTypeDescription
codeInteger0
dataArray of ObjectsAll the authentication information
data[].topicStringTopic
data[].usernameStringusername
data[].actionStringAction
data[].accessStringIf allowed

Request Example

bash
curl -u app_id:app_secret -X GET {api}/acl/username/emqx_u_1

Response Example

JSON
{
  "data": [
    {
      "topic": "topic/A",
      "username": "emqx_u_1",
      "action": "pub",
      "access": "allow"
    }
  ],
  "code": 0
}

Delete ACL Rule Specified by Specific clientid

URI

DELETE /acl/clientid/{clientid}/topic/{topic}

Parameter

NameTypeDescription
clientidStringClient ID
topicStringtopic, may need to use UrlEncode encoding

Request Message

None.

Response Message

NameTypeDescription
codeInteger0

Request Example

bash
curl -u app_id:app_secret -X DELETE {api}/acl/clientid/emqx_c_1/topic/topic%2fA

Response Example

JSON
{
  "code": 0
}

Delete the ACL Rule Specified by Specific username

URI

DELETE /acl/username/{username}/topic/{topic}

Parameter

NameTypeDescription
usernameStringusername
topicStringtopic, may need to use UrlEncode encoding

Request Message

None.

Response Message

NameTypeDescription
codeInteger0

Request Example

bash
curl -u app_id:app_secret -X DELETE {api}/acl/username/emqx_u_1/topic/topic%2fA

Response Example

JSON
{
  "code": 0
}

Delete ACL Rules Specified by Based on All

URI

DELETE /acl/$all/topic/{topic}

Parameter

NameTypeDescription
topicStringtopic, may need to use UrlEncode encoding

Request Message

None.

Response Message

NameTypeDescription
codeInteger0

Request Example

bash
curl -u app_id:app_secret -X DELETE {api}/acl/all/\$all/topic/topic%2uA

Response Example

JSON
{
  "code": 0
}