Working with ACLs using the API

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:

• Service ID: The ID of the Fastly service the ACL is associated with.
• Service Version Number: The service version number the ACL is associated with. Note that the ACL will continue to reside within subsequently cloned counterparts.
• ACL Name: The name of the ACL.
• ACL ID: The unique identifier of the ACL.

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:

1
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:

1
2
3
4
5
6
7
8
{
    "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:

1
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:

1
2
3
4
5
6
7
8
{
    "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:

1
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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
[
    {
        "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:

1
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:

1
2
3
{
  "status":"ok"
}

Working with ACL entries using the API

ACL entry parameters

ACL entries have the following parameters:

• service_id: The ID of the Fastly service the ACL is associated with.
• acl_id: The ID of the ACL.
• id: The ID of the ACL entry.
• ip: The IP address contained within the ACL entry.
• subnet: Optional. The range of IP addresses within a single ACL entry.
• negated: If true, this entry is an exception to the non-negated entries in the list. Negations override non-negated entries regardless of their order. Valid values are true and false. Defaults to false.
• comment: Optional. A descriptive comment indicating why you created the ACL entry.

Creating an ACL entry

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

1
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:

1
2
3
4
5
6
7
8
9
10
11
12
{
    "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:

1
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:

1
2
3
4
5
6
7
8
9
10
11
12
{
    "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:

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

The response will look like this:

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
[
    {
        "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:

1
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:

1
2
3
4
5
6
7
8
9
10
11
12
{
    "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:

1
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:

1
2
3
{
  "status":"ok"
}

Deleting an ACL entry

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

1
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:

1
2
3
{
  "status":"ok"
}