Getting started
Basics
Domains & Origins
Performance

Configuration
Basics
Conditions
Dictionaries
Domains & Origins
Request settings
Cache settings
Headers
Responses
Performance
Custom VCL
Image optimization
Video

Security
Access Control Lists
Monitoring and testing
Securing communications
Security measures
TLS
Web Application Firewall

Integrations
Logging endpoints
Non-Fastly services

Diagnostics
Streaming logs
Debugging techniques
Common errors

Account info
Account management
Billing
User access and control

Reference

    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:

    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:

    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"
    }
    
    Back to Top

    Additional resources: