ACL API reference

You are browsing documentation for an outdated plugin version.

Using the ACLs API

The ACL plugin exposes endpoints for configuring ACLs.

To configure and enable the plugin itself, use the /plugins API endpoint. The /acls endpoints only appear once the plugin has been enabled.

Return ACLs

Retrieves paginated ACLs.

curl -X GET http://localhost:8001/acls

Result:

{
    "total": 3,
    "data": [
        {
            "group": "foo-group",
            "created_at": 1511391159000,
            "id": "724d1be7-c39e-443d-bf36-41db17452c75",
            "consumer": { "id": "89a41fef-3b40-4bb0-b5af-33da57a7ffcf" }
        },
        {
            "group": "bar-group",
            "created_at": 1511391162000,
            "id": "0905f68e-fee3-4ecb-965c-fcf6912bf29e",
            "consumer": { "id": "c0d92ba9-8306-482a-b60d-0cfdd2f0e880" }
        },
        {
            "group": "baz-group",
            "created_at": 1509814006000,
            "id": "ff883d4b-aee7-45a8-a17b-8c074ba173bd",
            "consumer": { "id": "c0d92ba9-8306-482a-b60d-0cfdd2f0e880" }
        }
    ]
}

Retrieve ACLs by consumer

Retrieves ACLs by consumer.

curl -X GET http://localhost:8001/consumers/{CONSUMER}/acls

Result:

{
    "total": 1,
    "data": [
        {
            "group": "bar-group",
            "created_at": 1511391162000,
            "id": "0905f68e-fee3-4ecb-965c-fcf6912bf29e",
            "consumer": { "id": "c0d92ba9-8306-482a-b60d-0cfdd2f0e880" }
        }
    ]
}

CONSUMER: The username or id of the consumer.

Retrieve ACL by ID

Retrieves ACL by ID if the ACL belongs to the specified consumer.

curl -X GET http://localhost:8001/consumers/{CONSUMER}/acls/{ID}

Result:

{
    "group": "foo-group",
    "created_at": 1511391159000,
    "id": "724d1be7-c39e-443d-bf36-41db17452c75",
    "consumer": { "id": "89a41fef-3b40-4bb0-b5af-33da57a7ffcf" }
}

CONSUMER: The username property of the consumer entity.

ID: The id property of the ACL.

Retrieve the consumer associated with an ACL

Retrieves a consumer associated with an ACL using the following request:

curl -X GET http://localhost:8001/acls/{ID}/consumer

Result:

{
   "created_at":1507936639000,
   "username":"foo",
   "id":"c0d92ba9-8306-482a-b60d-0cfdd2f0e880"
}

ID: The id property of the ACL.

Assign a consumer to an ACL group

Assign a consumer to an existing ACL group, previously configured via the ACL plugin’s config.

curl -X POST http://localhost:8001/consumers/{CONSUMER}/acls \
    --data "group=group1"

CONSUMER: The username property of the consumer entity.

Update an ACL group by ID

Updates an ACL group name by passing a new group name.

curl -X PUT http://localhost:8001/consumers/{CONSUMER}/acls/{ID}
  --data "group=newgroupname"

CONSUMER: The username property of the consumer entity.

ID: The id property of the ACL.

Remove an ACL group for a consumer

Deletes an ACL group by ID or group name.

curl -X DELETE http://localhost:8001/consumers/{CONSUMER}/acls/{ID}

ID: The id property of the ACL.

Deletes an ACL group by group name.

curl -X DELETE http://localhost:8001/consumers/{CONSUMER}/acls/{GROUP}

GROUP: The group property of the ACL.

A successful DELETE request returns a 204 status.