From 72292d4d0130caeaebb982ee7ecfef649bca91ca Mon Sep 17 00:00:00 2001
From: Krzysztof Jeziorny <872730+krzysztofjeziorny@users.noreply.github.com>
Date: Sun, 29 Sep 2024 16:59:15 +0200
Subject: [PATCH] Documentation: Configure API to use the DRF's
 TokenAuthentication (#12363)

Co-authored-by: Thibaud Colas <thibaudcolas@gmail.com>
---
 CHANGELOG.txt                                |  1 +
 docs/advanced_topics/api/v2/configuration.md | 48 ++++++++++++++++++++
 docs/releases/6.3.md                         |  1 +
 3 files changed, 50 insertions(+)

diff --git a/CHANGELOG.txt b/CHANGELOG.txt
index 0492741075..cea43d097b 100644
--- a/CHANGELOG.txt
+++ b/CHANGELOG.txt
@@ -38,6 +38,7 @@ Changelog
  * Docs: Clarify process for UserViewSet customization (Sage Abdullah)
  * Docs: Correct `WAGTAIL_WORKFLOW_REQUIRE_REAPPROVAL_ON_EDIT` documentation to state that it defaults to `False` (Matt Westcott)
  * Docs: Add an example of customizing a default accessibility check (Cynthia Kiser)
+ * Docs: Demonstrate access protection with `TokenAuthentication` in the Wagtail API v2 Configuration Guide (Krzysztof Jeziorny)
  * Maintenance: Removed support for Python 3.8 (Matt Westcott)
  * Maintenance: Drop pytz dependency in favour of `zoneinfo.available_timezones` (Sage Abdullah)
  * Maintenance: Relax django-taggit dependency to allow 6.0 (Matt Westcott)
diff --git a/docs/advanced_topics/api/v2/configuration.md b/docs/advanced_topics/api/v2/configuration.md
index d06b38a126..08603c0574 100644
--- a/docs/advanced_topics/api/v2/configuration.md
+++ b/docs/advanced_topics/api/v2/configuration.md
@@ -290,6 +290,54 @@ a URL to the image if your media files are properly configured.
 
 For cases where the source image set may contain SVGs, the `ImageRenditionField` constructor takes a `preserve_svg` argument. The behavior of `ImageRenditionField` when `preserve_svg` is `True` is as described for the `image` template tag's `preserve-svg` argument (see the documentation on [](svg_images)).
 
+### Authentication
+
+To protect the access to your API, you can implement an [authentication](https://www.django-rest-framework.org/api-guide/authentication/) method provided by the Django REST Framework, for example the [Token Authentication](https://www.django-rest-framework.org/api-guide/authentication/#tokenauthentication):
+
+```python
+# api.py
+
+from rest_framework.permissions import IsAuthenticated
+
+# ...
+
+class CustomPagesAPIViewSet(PagesAPIViewSet):
+    name = "pages"
+    permission_classes = (IsAuthenticated,)
+
+
+api_router.register_endpoint("pages", CustomPagesAPIViewSet)
+```
+
+Extend settings with
+
+```python
+# settings.py
+
+INSTALLED_APPS = [
+    ...
+
+    'rest_framework.authtoken',
+
+    ...
+]
+
+...
+
+REST_FRAMEWORK = {
+    "DEFAULT_AUTHENTICATION_CLASSES": [
+        "rest_framework.authentication.TokenAuthentication"
+    ],
+}
+```
+
+Don't forget to run the app's migrations.
+
+Your API endpoint will be accessible only with the Authorization header containing the generated `Token exampleSecretToken123xyz`.
+Tokens can be generated in the Django admin under Auth Token or using the `manage.py` command `drf_create_token`.
+
+Note: If you use `TokenAuthentication` in production you must ensure that your API is only available over `https`.
+
 ## Additional settings
 
 ### `WAGTAILAPI_BASE_URL`
diff --git a/docs/releases/6.3.md b/docs/releases/6.3.md
index e439ef86fd..1e81aca91d 100644
--- a/docs/releases/6.3.md
+++ b/docs/releases/6.3.md
@@ -59,6 +59,7 @@ This release adds formal support for Django 5.1.
  * Clarify process for [UserViewSet customization](custom_userviewset) (Sage Abdullah)
  * Correct `WAGTAIL_WORKFLOW_REQUIRE_REAPPROVAL_ON_EDIT` documentation to state that it defaults to `False` (Matt Westcott)
  * Add an example of customizing a default accessibility check (Cynthia Kiser)
+ * Demonstrate access protection with `TokenAuthentication` in the [Wagtail API v2 Configuration Guide](/advanced_topics/api/v2/configuration) (Krzysztof Jeziorny)
 
 
 ### Maintenance