---
title: Authenticating URL purge requests via API
summary: null
url: >-
  https://www.fastly.com/documentation/guides/full-site-delivery/purging/authenticating-api-purge-requests
---

Fastly's [URL purge](https://www.fastly.com/documentation/guides/full-site-delivery/purging/purging-a-url) 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](https://www.fastly.com/documentation/guides/account-info/user-and-account-management/using-api-tokens) authentication in the Fastly control panel by adding a header or by using custom VCL.

> **WARNING:** We recommend that all customers enable authentication for URL purge requests.

> **NOTE:** All purge requests other than URL purges require authentication by default, as indicated in the [API documentation](https://www.fastly.com/documentation/reference/api/purging/).

## Limitations and considerations

Keep in mind the following limitations and considerations when authenticating URL purge requests via API:

- 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, [contact support](https://support.fastly.com).
- [Segmented caching](https://www.fastly.com/documentation/guides/full-site-delivery/caching/segmented-caching/) allows you to purge all range objects for the resource by URL purge, but authentication for URL purge needs to be enabled due to its underlying implementation.

## Enabling authentication in the Fastly control panel

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

### Adding the header

1.   Log in to the [Fastly control panel](https://manage.fastly.com).

2.   From the [**Home**](https://manage.fastly.com/home) page, select the appropriate service. You can use the search box to search by ID, name, or domain.

3.   Click **Edit configuration** and then select the option to clone the active version.

4.   Click **Content**.

5. Click **Create header**.

   ![Create a header window](/img/new-header-purge.png)

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 **Create**.

### 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 **Attach a condition** to the right of your new header.

   ![Create a new request condition window](/img/new-condition-purge.png)

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 **Save and apply to**.

4.   From the **Activate** menu, select **Activate on Production** to deploy your configuration changes.

## Enabling authentication with VCL snippets

You can also enable API token authentication for URL purge requests using [VCL snippets](https://www.fastly.com/documentation/guides/full-site-delivery/fastly-vcl/vcl-snippets/using-vcl-snippets). Refer to the [developer documentation](https://www.fastly.com/documentation/guides/concepts/cache/purging/#url-purge) for details on setting the `Fastly-Purge-Requires-Auth` header.

## Purging URLs with an API token

> **WARNING:** If your website is not configured to use HTTPS, do not use the Fastly API to purge URLs. Doing so could expose your API token since the data in transit will not be encrypted.

After you've enabled API token authentication for URL purge requests, you'll need to provide your [API token](https://www.fastly.com/documentation/guides/account-info/user-and-account-management/using-api-tokens) in the [URL purge API request](https://www.fastly.com/documentation/reference/api/purging/):

```term copy
$ curl -X PURGE -H Fastly-Key:FASTLY_API_TOKEN https://www.example.com/
```

which would return this response:

```term nolinenums
{"status": "ok", "id": "1234567890"}
```