We've been making changes to how we organize and display our docs. Our work isn't done but we'd love your feedback.
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
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

    Authenticating URL purge requests via API

      Last updated October 08, 2018

    Fastly's URL purge feature allows you to purge individual URLs on your website. By default, authentication is not required to purge a URL with the Fastly API, but you can enable API token authentication in the Fastly web interface by adding a header or by using custom VCL.

    Enabling authentication in the Fastly web interface

    You can enable API token authentication for URL purge requests by adding a header and optionally attaching a condition in the Fastly web interface.

    Adding the header

    1. Log in to the Fastly web interface and click the Configure link.
    2. From the service menu, select the appropriate service.
    3. Click the Configuration button and then select Clone active. The Domains page appears.
    4. Click the Content link. The Content page appears.
    5. Click the Create header button. The Create a header window appears.

      Create a header window

    6. Fill out the Create a header fields as follows:
      • In the Name field, type the name of your header rule (for example, Fastly Purge).
      • From the Type menu, select Request, and from the Action menu, select Set.
      • In the Destination field, type http.Fastly-Purge-Requires-Auth.
      • In the Source field, type "1".
      • From the Ignore if set menu, select No.
      • In the Priority field, type 10.
    7. Click the Create button.

    Attaching a condition

    Attaching the following condition is optional. Without the condition, the header you just created will be added to all requests. With the condition, the header will be added to purge requests only.

    1. On the Content page, click the Attach a condition link to the right of your new header. The Create a new request condition window appears.

      Create a new request condition window

    2. Fill out the Create a new request condition fields as follows:
      • In the Name field, type a descriptive name for the new condition (for example, Purge).
      • In the Apply if field, type req.method == "FASTLYPURGE".
    3. Click the Save and apply to button.
    4. Click the Activate button to deploy your configuration changes.

    Enabling authentication with VCL Snippets

    You can also enable API token authentication for URL purge requests using VCL Snippets:

    1. Log in to the Fastly web interface and click the Configure link.
    2. From the service menu, select the appropriate service.
    3. Click the Configuration button and then select Clone active. The Domains page appears.
    4. Click the VCL Snippets link. The VCL Snippets page appears.
    5. Click Create Snippet. The Create a VCL snippet page appears.

      enabling API authentication vcl snippet

    6. In the Name field, type an appropriate name (e.g., Purge Require Auth).
    7. From the Type controls, select within subroutine.
    8. From the Select subroutine menu, select recv (vcl_recv).
    9. In the VCL field, add the following condition:

      1
      2
      3
      
      if (req.method == "FASTLYPURGE") {
          set req.http.Fastly-Purge-Requires-Auth = "1";
      }
      
    10. Click Create to create the snippet.
    11. Click the Activate button to deploy your configuration changes.

    Purging URLs with an API token

    After you've enabled API token authentication for URL purge requests, you'll need to provide your API token in the URL purge API request:

    1
    
    curl -X PURGE -H Fastly-Key:FASTLY_API_TOKEN https://www.example.com/
    

    which would return this response:

    1
    
    {"status": "ok", "id": "1234567890"}
    
    Back to Top