Authenticating URL purge requests via API

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.

Limitations and considerations

This feature has the following limitations and considerations you should take into account:

• URL purge authentication is not compatible with the Purge URL option in the Fastly web interface. Enabling purge authentication will cause the Purge URL interface to return an error when used.
• The solution outlined in this guide must be implemented on every service that requires authentication of URL purge requests. To enable purge authentication at the account level, email support@fastly.com.

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.
2. From the All services page, select the appropriate service. You can use the search box to search by ID, name, or domain.
3. Click the Edit configuration button and then select the option to clone the active version. 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.

   

6. Fill out the Create a header fields as follows:
   • In the Name field, enter 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, enter http.Fastly-Purge-Requires-Auth.
   • In the Source field, enter "1".
   • From the Ignore if set menu, select No.
   • In the Priority field, enter 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.

   

2. Fill out the Create a new request condition fields as follows:
   • In the Name field, enter a descriptive name for the new condition (for example, Purge).
   • In the Apply if field, enter req.request == "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.
2. From the All services page, select the appropriate service. You can use the search box to search by ID, name, or domain.
3. Click the Edit configuration button and then select the option to clone the active version. 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.

   

6. In the Name field, enter 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.request == "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"}