LOG IN SIGN UP
Documentation

Working with ACLs using the API

  Last updated July 30, 2018

Access control lists (ACLs) allow you to store a list of permissions that Varnish will use to grant or restrict access to URLs within your services. You can use the Fastly API to add, remove, and update ACLs programmatically.

Working with ACL containers using the API

Using the Fastly API, you can create view, or delete ACL containers into which ACL entries can be placed.

ACL container attributes

Containers for ACLs at the edge have the following attributes:

Creating an ACL container

To start using an ACL, you'll need to create an empty container within a version of a service that's unlocked and not yet activated. Make the following API call in a terminal application:

curl -H "Fastly-Key: FASTLY_API_TOKEN" -X POST https://api.fastly.com/service/<service_id>/version/<service_version_number>/acl -d name=my_acl

The response will look like this:

{
    "id": "<service_version_number>",
    "name": "my_acl",
    "service_id": "<service_id>",
    "version": "1",
    "created_at": "2016-04-14 21:23:21",
    "updated_at": "2016-04-14 21:23:21"
}

Be sure to activate the new version of the service you associated with the empty ACL container.

Viewing ACL containers

To see information related to a single ACL (in this example, my_acl) attached to a particular version of a service, make the following API call in a terminal application:

curl -H "Fastly-Key: FASTLY_API_TOKEN" https://api.fastly.com/service/<service_id>/version/<service_version_number>/acl/my_acl

The response will look like this:

{
    "id": "<acl_id>",
    "name": "my_acl",
    "service_id": "<service_id>",
    "version": "<service_version_number>",
    "created_at": "2016-04-14 21:23:21",
    "updated_at": "2016-04-14 21:23:21"
}

To view a list of all ACL containers attached to a particular version of a service, make the following API call in a terminal application:

curl -H "Fastly-Key: FASTLY_API_TOKEN" https://api.fastly.com/service/<service_id>/version/<service_version_number>/acl

The response will look like this:

[
    {
        "id": "<acl_1_id>",
        "name": "my_new_acl",
        "service_id": "<service_id>",
        "version": "<service_version_number>",
        "created_at": "2016-04-14 21:23:21",
        "updated_at": "2016-04-15 17:23:09"
},
    {
        "id": "<acl_2_id>",
        "name": "my_other_acl",
        "service_id": "<service_id>",
        "version": "<service_version_number>",
        "created_at": "2016-04-14 21:23:21",
        "updated_at": "2016-04-15 17:23:09"
    }
]

Deleting an ACL container

Deleting an ACL deletes the ACL and all of its associated entries. To delete an ACL (in this example, my_new_acl), make the following API call in a terminal application:

curl -H "Fastly-Key: FASTLY_API_TOKEN" -X DELETE https://api.fastly.com/service/<service_id>/version/<service_version_number>/acl/my_new_acl

The response will look like this:

{
  "status":"ok"
}

Working with ACL entries using the API

ACL entry parameters

ACL entries have the following parameters:

Creating an ACL entry

To add an entry to an existing ACL, make the following API call in a terminal application:

curl -H "Fastly-Key: FASTLY_API_TOKEN" -X POST https://api.fastly.com/service/<service_id>/acl/<acl_id>/entry -d 'ip=127.0.0.1&subnet=16&negated=0&comment=test'

The response will look like this:

{
    "acl_id": "<acl_id>",
    "comment": "test",
    "created_at": "2016-04-22T19:14:02+00:00",
    "deleted_at": null,
    "id": "<acl_entry_id>",
    "ip": "127.0.0.1",
    "negated": "0",
    "service_id": "<service_id>",
    "subnet": 16,
    "updated_at": "2016-04-22T19:14:02+00:00"
}

Viewing ACL entries

To see information related to a single ACL entry, make the following API call in a terminal application:

curl -H "Fastly-Key: FASTLY_API_TOKEN" -H 'Content-Type: application/vnd.api+json' https://api.fastly.com/service/<service_id>/acl/<acl_id>/entry/<acl_entry_id>

The response will look like this:

{
    "acl_id": "<acl_id>",
    "comment": "",
    "created_at": "2016-04-22T19:18:42+00:00",
    "deleted_at": null,
    "id": "<acl_entry_id>",
    "ip": "127.0.0.5",
    "negated": "0",
    "service_id": "<service_id>",
    "subnet": 16,
    "updated_at": "2016-04-22T19:18:42+00:00"
}

To view a list of all ACL entries attached to a particular ACL, make the following API call in a terminal application:

curl -H "Fastly-Key: FASTLY_API_TOKEN" https://api.fastly.com/service/<service_id>/acl/<acl_id>/entries

The response will look like this:

[
    {
        "acl_id": "<acl_id>",
        "comment": "",
        "created_at": "2016-04-22T19:13:03+00:00",
        "deleted_at": null,
        "id": "<acl_entry_1_id>",
        "ip": "127.0.0.1",
        "negated": "0",
        "service_id": "<service_id>",
        "subnet": 16,
        "updated_at": "2016-04-22T19:13:03+00:00"
    },
    {
        "acl_id": "<acl_id>",
        "comment": "",
        "created_at": "2016-04-22T19:14:02+00:00",
        "deleted_at": null,
        "id": "<acl_entry_2_id>",
        "ip": "127.0.0.2",
        "negated": "0",
        "service_id": "<service_id>",
        "subnet": 16,
        "updated_at": "2016-04-22T19:14:02+00:00"
    }
]

Updating ACL entries

There are two ways to update ACL entries: you can update a single ACL entry, or you can update multiple ACL entries at the same time.

Updating a single ACL entry

To update an existing ACL entry, make the following API call in a terminal application:

curl -H "Fastly-Key: FASTLY_API_TOKEN" -X PATCH https://api.fastly.com/service/<service_id>/acl/<acl_id>/entry/<acl_entry_id> -d 'ip=127.0.0.2&subnet=32&negated=0&comment=allow'

The response will look like this:

{
    "acl_id": "<acl_id>",
    "comment": "allow",
    "created_at": "2016-04-22T19:18:42+00:00",
    "deleted_at": null,
    "id": "<acl_entry_id>",
    "ip": "127.0.0.2",
    "negated": "0",
    "service_id": "<service_id>",
    "subnet": 32,
    "updated_at": "2016-04-22T19:18:42+00:00"
}

Updating multiple ACL entries

You can also update multiple ACL entries at the same time. Include an entries array of changes in the API call and pass an operation (op) parameter for every change. Possible op values are create, update, and delete.

To update multiple ACL entries at the same time, make the following API call in a terminal application:

curl -H "Fastly-Key: FASTLY_API_TOKEN" -H "Content-type: application/json" -X PATCH https://api.fastly.com/service/<service_id>/acl/<acl_id>/entries -d '{"entries":[{"op": "create", "ip": "192.168.0.1","subnet": "8"},{"op": "update", "id": "<acl_entry_id>", "ip": "192.168.0.2", "subnet": "16"},{"op": "delete", "id": "<acl_entry_id>"}]}'

The response will look like this:

{
  "status":"ok"
}

Deleting an ACL entry

To permanently delete an ACL entry, make the following API call in a terminal application:

curl -H "Fastly-Key: FASTLY_API_TOKEN" -X DELETE https://api.fastly.com/service/<service_id>/acl/<acl_id>/entry/<acl_entry_id>

The response will look like this:

{
  "status":"ok"
}

Additional resources:


Back to Top