Working with ACLs using the API
Last updated 2018-07-30
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 unique identifier 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 aretrueandfalse. Defaults tofalse.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
ACL entry deletions are permanent. If you delete an ACL entry, the entry is permanently removed from all service versions and cannot be recovered.
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"
}