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.
NOTE: All purge requests other than URL purges require authentication by default, as indicated in the API documentation.
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
- Log in to the Fastly web interface and click the Configure link.
- From the service menu, select the appropriate service.
- Click the Edit configuration button and then select Clone active. The Domains page appears.
- Click the Content link. The Content page appears.
-
Click the Create header button. The Create a header window appears.
- 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
.
- In the Name field, type the name of your header rule (for example,
- 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.
-
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.
- 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.request == "FASTLYPURGE"
.
- In the Name field, type a descriptive name for the new condition (for example,
- Click the Save and apply to button.
- 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:
- Log in to the Fastly web interface and click the Configure link.
- From the service menu, select the appropriate service.
- Click the Edit configuration button and then select Clone active. The Domains page appears.
- Click the VCL Snippets link. The VCL Snippets page appears.
-
Click Create Snippet. The Create a VCL snippet page appears.
- In the Name field, type an appropriate name (e.g., Purge Require Auth).
- From the Type controls, select within subroutine.
- From the Select subroutine menu, select recv (vcl_recv).
-
In the VCL field, add the following condition:
1 2 3
if (req.request == "FASTLYPURGE") { set req.http.Fastly-Purge-Requires-Auth = "1"; }
- Click Create to create the snippet.
- 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"}
WARNING: If your website is not configured to use HTTPS, we recommend purging using a POST request with a secure Fastly API URL. This will ensure that your API token in the header is encrypted in transit. The request will look like this: curl -X POST -H Fastly-Key:FASTLY_API_TOKEN https://api.fastly.com/purge/<your_url_here>
.