# Access Control(ACL) Management

# Create ACL Rule Based on clientid

# URI

POST /acl

# Request Message

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

# Response Message

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

# Request Example

$ curl -u app_id:app_secret -X POST {api}/acl
1
{
  "clientid": "client1",
  "topic": "a/b",
  "action": "sub",
  "access": "allow"
}
1
2
3
4
5
6

# Response Example

{
"data": {
"topic": "a/b",
"result": "ok",
"clientid": "client1",
"action": "sub",
"access": "allow"
},
"code": 0
}
1
2
3
4
5
6
7
8
9
10

# Create ACL Rule Based on username

# URI

POST /acl

# Request Message

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

# Response Message

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

# Request Example

$ curl -u app_id:app_secret -X POST {api}/acl
1
{
  "username": "user1",
  "topic": "a/b",
  "action": "sub",
  "access": "allow"
}
1
2
3
4
5
6

# Response Example

{
  "data": {
    "topic": "a/b",
    "result": "ok",
    "username": "user1",
    "action": "sub",
    "access": "allow"
  },
  "code": 0
}
1
2
3
4
5
6
7
8
9
10

# Create ACL Rule Based on Everything

# URI

POST /acl

# Request Message

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

# Response Message

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

# Request Example

$ curl -u app_id:app_secret -X POST {api}/acl
1
{
  "topic": "a/b",
  "action": "pub",
  "access": "allow"
}
1
2
3
4
5

# Response Example

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

1
2
3
4
5
6
7
8
9
10
11

# Batch Add ACL Rule

# URI

POST /acl

# Request Message

NameTypeDescription
[0].clientidString[0].clientid
[0].topicStringTopic
[0].actionStringAction: sub, pub, subpub
[0].accessStringIf allowed: allow, deny
[1].usernameStringusername
[1].topicStringTopic
[1].actionStringAction: sub, pub, subpub
[1].accessStringIf allowed: allow, deny
[2].topicStringTopic
[2].actionStringAction: sub, pub, subpub
[2].accessStringIf allowed: allow, deny

# Response Message

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

# Request Example

$ curl -u app_id:app_secret -X POST {api}/acl
1
[
  {
    "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"
  }
]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# Response Example

{
  "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
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

# Check ACL Rules Based on client id

# 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

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

# Response Example

{
  "meta": {
    "page": 1,
    "limit": 10,
    "count": 1
  },
  "data": [
    {
      "topic": "topic/A",
      "clientid": "emqx_c_1",
      "action": "pub",
      "access": "allow"
    }
  ],
  "code": 0
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# Check ACL Rules Based on 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

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

# Response Example

{
  "meta": {
    "page": 1,
    "limit": 10,
    "count": 1
  },
  "data": [
    {
      "username": "emqx_u_1",
      "topic": "topic/A",
      "action": "sub",
      "access": "allow"
    }
  ],
  "code": 0
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

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

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

# Response Example

{
  "meta": {
    "page": 1,
    "limit": 10,
    "count": 1
  },
  "data": [
    {
      "topic": "topic/A",
      "all": "$all",
      "action": "sub",
      "access": "allow"
    }
  ],
  "code": 0
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# Check ACL Rules for Specified Client Id

# URI

GET /acl/clientid/{clientid}

# Parameter

NameTypeDescription
clientidStringclientid

# Request Message

None

# Response Message

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

# Request Example

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

# Response Example

{
  "data": [
    {
      "topic": "topic/A",
      "clientid": "emqx_c_1",
      "action": "pub",
      "access": "allow"
    }
  ],
  "code": 0
}
1
2
3
4
5
6
7
8
9
10
11

# Check ACL Rules for 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

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

# Response Example

{
  "data": [
    {
      "topic": "topic/A",
      "username": "emqx_u_1",
      "action": "pub",
      "access": "allow"
    }
  ],
  "code": 0
}
1
2
3
4
5
6
7
8
9
10
11

# Delete the ACL Rule Specified by the Specified client id

# URI

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

# Parameter

NameTypeDescription
clientidStringclientid
topicStringtopic, may need to use UrlEncode encoding

# Request Message

None

# Response Message

NameTypeDescription
codeInteger0

# Request Example

$ curl -u app_id:app_secret -X DELETE {api}/acl/clientid/emqx_c_1/topic/topic%2uA
1

# Response Example

{
  "code": 0
}
1
2
3

# Delete the ACL Rule Specified by the Specified 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

$ curl -u app_id:app_secret -X DELETE {api}/acl/username/emqx_u_1/topic/topic%2uA
1

# Response Example

{
  "code": 0
}
1
2
3

# Delete based on All Specified ACL Rules

# URI

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

# Parameter

NameTypeDescription
topicStringtopic, may need to use UrlEncode encoding

# Request Message

None

# Response Message

NameTypeDescription
codeInteger0

# Request Example

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

# Response Example

{
  "code": 0
}
1
2
3